Meziantou.Framework

Identifying symbols

edit

Find a symbol

FindSymbolByDocumentationId finds a type or a member by its XML documentation ID, and FindType finds a type, including a nested type, by its metadata full name. For this type, declared in the PublicApiGeneratorTests class of the Meziantou.Framework.PublicApiGenerator.Tests namespace:

public sealed class MyType<T>
{
    public List<string?> MyMethod(int value) => [];

    public sealed class Nested;
}
var symbol = assembly.FindSymbolByDocumentationId("M:Meziantou.Framework.PublicApiGenerator.Tests.PublicApiGeneratorTests.MyType`1.MyMethod(System.Int32)");
var type = assembly.FindType("Meziantou.Framework.PublicApiGenerator.Tests.PublicApiGeneratorTests+MyType`1+Nested");

Both return null when the assembly has no such public symbol. Metadata names use a backtick and the number of generic parameters for generic types (MyType`1), and + between a type and its nested types.

Documentation IDs, identities and metadata tokens

Each symbol exposes three kinds of identifiers:

  • DocumentationId: the XML documentation ID generated by the C# compiler (such as M:MyNamespace.MyType.MyMethod(System.Int32)). Use it to find the documentation of a symbol in the XML documentation file of the assembly, or to resolve a cref. It is not unique across assemblies: the builds of an assembly for several target frameworks, or unrelated assemblies, can declare the same documentation ID.
  • Identity: the documentation ID scoped to its assembly (PublicApiAssembly.Scope). The scope is PublicApiReadOptions.InputIdentity when it is provided; otherwise it is made of the assembly display name and of the module version ID (MVID), so it changes when the assembly is rebuilt with different inputs. It never contains a file path.
  • Origin: the metadata token of the entity the symbol was read from, with the MVID of its module. Tokens are not stable across builds and are only meaningful for their module. Use them, with PublicApiModule.PdbReferences, to find the debug information (such as sequence points) of a symbol. Accessors have their own origin.

Set the input identity

Set PublicApiReadOptions.InputIdentity when you read assemblies you can name, such as the assemblies of a package: use the package identity and the path of the assembly in the package, for instance MyPackage/1.0.0/lib/net10.0/MyLibrary.dll, as in the example of Reading the API model. The identities of the symbols are then the same on every machine and for every build of that input. Avoid machine-specific values, such as absolute file paths.