smdn/Smdn.Reflection.ReverseGenerating

.NET libraries and tools to reverse-generate C# code from type and member information using reflection

This repository provides the libraries and tools to reverse-generate C# code that describes the type and member information, from the .NET assemblies.

By generating an API list from the library, the types and members provided by the library can be presented in C# code format. This allows you to present an outline of the library API to users in addition to explaining the API through text or sample code.

Smdn.Reflection.ReverseGenerating.ListApi.MSBuild.Tasks

This package provides GenerateApiList MSBuild task.

Usage

See examples for details and more usage examples.

  <ItemGroup>
    <!-- Add package reference of Smdn.Reflection.ReverseGenerating.ListApi.MSBuild.Tasks. -->
    <PackageReference
      Include="Smdn.Reflection.ReverseGenerating.ListApi.MSBuild.Tasks"
      Version="*"
      PrivateAssets="all"
      IncludeAssets="build"
    />
  </ItemGroup>

  <ItemGroup>
    <!-- Specify target assemblies to generate API list. -->
    <GenerateApiListTargetAssemblies Include="..." />
  </ItemGroup>

  <PropertyGroup>
    <!-- (Optional) If you want to import 'Smdn.Reflection.ReverseGenerating.ListApi.MSBuild.Tasks.targets' even if the build target is `pack`. -->
    <ExcludeRestorePackageImports>false</ExcludeRestorePackageImports>
  </PropertyGroup>

  <Target Name="GenerateApiListFromAssemblies" AfterTargets="Pack">
    <!-- Call `GenerateApiList` task -->
    <GenerateApiList Assemblies="@(GenerateApiListTargetAssemblies)">
      <Output TaskParameter="GeneratedFiles" ItemName="GeneratedApiListFiles" />
    </GenerateApiList>

    <Message Text="generated API list: @(GeneratedApiListFiles)" Importance="high" />
  </Target>

Smdn.Reflection.ReverseGenerating.ListApi

This package provides list-api command line tool.

Installation

Use dotnet tool to install or update list-api command.

# install
dotnet tool install -g Smdn.Reflection.ReverseGenerating.ListApi

# update
dotnet tool update -g Smdn.Reflection.ReverseGenerating.ListApi

# install and update (specifies the target framework explicitly)
dotnet tool install --framework net6.0 -g Smdn.Reflection.ReverseGenerating.ListApi
dotnet tool update --framework net8.0 -g Smdn.Reflection.ReverseGenerating.ListApi

Usage

# Generates the API list.
# The file 'Library-net8.0.apilist.cs' will be generated.
list-api Library/bin/Release/net8.0/Library.dll

# Generates the API list with loading the assembly in the reflection-only context.
list-api --load-reflection-only Library/bin/Release/net8.0/Library.dll

Type list-api --help to show usage about command line arguments and options.

If you are loading an assembly that targets a newer version than the runtime version that the list-api command targets, try running it with the DOTNET_ROLL_FORWARD environment variable.

# Installs list-api targeting .NET 6.0
dotnet tool install --framework net6.0 -g Smdn.Reflection.ReverseGenerating.ListApi

# Uses runtime roll forwarding to load the assembly targeting .NET 8.0
DOTNET_ROLL_FORWARD=LatestMajor list-api Library/bin/Release/net8.0/Library.dll

Limitations

This tool does not provide any options for code styles including spaces, indents, and new lines. Use dotnet format after generating to format such code styles.

Smdn.Reflection.ReverseGenerating

This package provides APIs common to reverse generating. See examples or API list of Smdn.Reflection.ReverseGenerating.

Example of output

The files in API list directory is generated using the artifacts of this repository.

For contributers

Contributions are appreciated!

If there's a feature you would like to add or a bug you would like to fix, please read Contribution guidelines and create an Issue or Pull Request.

IssueやPull Requestを送る際は、Contribution guidelinesをご覧頂ください。 可能なら英語が望ましいですが、日本語で構いません。