MetadataTools

A collection of small command-line tools for inspecting .NET assemblies on disk: their versions, references, signatures, debug info, MVIDs, and binary compatibility. Most are published as dotnet global tools.

For LLM agents: see llms.txt for a dense, token-conscious reference that teaches an agent the whole toolset in one file.

Dotnet global tools

Install / update any of them (dotnet tool update -g installs if missing, upgrades to latest if present):

dotnet tool update -g checkbinarycompat
dotnet tool update -g lbi
dotnet tool update -g refdump
dotnet tool update -g pdb

Other utilities (in this repo)

• FakeSign — toggle the StrongNameSigned bit in the COR header of a managed assembly. FakeSign foo.dll marks a delay-signed assembly as signed so the runtime will load it without a real key; FakeSign foo.dll -u un-signs; add -f to force when the assembly is already in the requested state.
• Corflags — clear the Prefers32Bit / Requires32Bit flags in the COR header: corflags foo.exe /32BITPREF-.
• DumpAssembly — dump types/methods of an assembly using Mono.Cecil.
• DumpModules — list all managed modules loaded in a process dump.
• mvid — print the MVID of an assembly using a minimal embedded PE reader (~7 ms cold).
• SRMReader — sample usage of System.Reflection.Metadata.
• PEFile / PETree — sample PE-format inspection.
• PEFile.cs, ImageReader.cs — single-file helpers that can be dropped into any project to quickly determine if a file is a managed assembly, or to read its MVID, with no dependencies.
• LargeAddressAware — set the LargeAddressAware bit in a 32-bit executable to unlock the 4 GB user-mode address space.
• ReadAssemblyVersion — quickly read an assembly's version.

Common workflows

Binlogs — "how did this dll get here?" questions

The tools above answer what is on disk. They cannot answer how it got there — which Copy task produced this file, which NuGet package shipped it, what transitive dependency chain pulled in version 13.0.3 instead of 12.0.0. Those questions require an MSBuild binary log (.binlog):

• Capture one by adding /bl to your build: msbuild MySolution.sln /bl or dotnet build MySolution.sln /bl. It costs negligible build time and writes msbuild.binlog next to the build.
• Inspect interactively with the MSBuild Structured Log Viewer (msbuildlog.com, github.com/KirillOsenkov/MSBuildStructuredLog).
• From an LLM agent, use the binlogmcp MCP server (must be configured in your agent host). The two killer queries:
  • $copy <full path to X.dll> — explains where every copy of X.dll came from (producing task, project, NuGet source, content item, project reference).
  • $nuget <package> [version] — full NuGet dependency graph; traces which <PackageReference> or transitive chain forced a specific version.

Typical use: lbi/refdump/checkbinarycompat identify what is wrong on disk; the binlog explains why the build put it there. See llms.txt for the full playbook.

---

Library API: reading an assembly MVID from your own code

The sections below document C# library APIs for retrieving an assembly's MVID programmatically, not the CLI tools above. They're aimed at developers building their own tools. If you just want to print MVIDs on the command line, use lbi -mvid and stop here.

Mono.Cecil stripped down to a single file to read an assembly's MVID without dependencies. Here are the various ways to retrieve the MVID of an assembly:

ImageReader

Just embed this file: https://github.com/KirillOsenkov/MetadataTools/blob/master/src/PEFile/ImageReader.cs

var mvid = ImageReader.ReadAssemblyMvid(filePath);

Cold run on a warm file: 7ms

Or see this sample from Roslyn: https://github.com/dotnet/roslyn/blob/1c98fe1fc6ef122cb3bb436aa90a0ea729fdcf37/src/Compilers/Core/MSBuildTask/MvidReader.cs#L13

Mono.Cecil

https://www.nuget.org/packages/Mono.Cecil

var module = Mono.Cecil.ModuleDefinition.ReadModule(filePath);
var mvid = module.Mvid;

Cold run on a warm file: 16ms

Reflection

This has the downside that it loads the assembly:

var assemblyName = AssemblyName.GetAssemblyName(filePath);
var assembly = Assembly.Load(assemblyName);
var mvid = assembly.ManifestModule.ModuleVersionId;

Cold run on a warm file: 33ms

System.Reflection.Metadata

https://www.nuget.org/packages/System.Reflection.Metadata

Sample in Roslyn: https://github.com/dotnet/roslyn/blob/1c98fe1fc6ef122cb3bb436aa90a0ea729fdcf37/src/Compilers/Core/Portable/AssemblyUtilities.cs#L84

using (var stream = File.OpenRead(filePath))
{
    PEReader reader = new PEReader(stream);
    var metadataReader = reader.GetMetadataReader();
    var mvidHandle = metadataReader.GetModuleDefinition().Mvid;
    var mvid = metadataReader.GetGuid(mvidHandle);
}

Cold run on a warm file: 76ms

BenchmarkDotNet paints quite a different performance picture:

               Method |        Mean |    StdDev |
--------------------- |------------ |---------- |
  ReadUsingReflection | 208.2023 us | 0.4036 us |
         ReadUsingSRM |  98.9620 us | 0.3674 us |
       ReadUsingCecil | 153.1947 us | 0.3085 us |
 ReadUsingImageReader | 147.0230 us | 1.2618 us |