DotNetMetadata

A Swift library for reading and inspecting .NET metadata, including WinMD files, following the ECMA-335, Common Language Infrastructure (CLI) standard. Parsing IL is currently out of scope, but not off the table in the future.

Example

import DotNetMetadata

let context = AssemblyLoadContext()
let assembly = try context.load(path: #"C:\Windows\Microsoft.NET\Framework64\v4.0.30319\mscorlib.dll"#)
let typeDefinition = assembly.resolveTypeDefinition(fullName: "System.IDisposable")!
print("interface \(typeDefinition.name) {")
for method in typeDefinition.methods {
    print("  void \(method.name)()")
}
print("}")

Package.swift:

// swift-tools-version: 5.8
import PackageDescription

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(url: "https://github.com/tristanlabelle/swift-dotnetmetadata", branch: "main")
    ],
    targets: [
        .executableTarget(name: "MyTarget", dependencies: [
            .product(name: "DotNetMetadata", package: "swift-dotnetmetadata")
        ])
    ]
)

Building

Prerequisites:

• Windows 10 or above (building on other platforms should be possible but is untested)
• A Swift toolchain, version 5.8 or above
  • winget install --id Swift.Toolchain
• Visual Studio (any edition) with the Desktop C++ Workload
  • winget install --id Microsoft.VisualStudio.2022.Community --override "--quiet --add Microsoft.VisualStudio.Workload.NativeDesktop"
• A Windows SDK
  • Comes with Visual Studio, or use winget install --id Microsoft.WindowsSDK.10.0.22000
• CMake and ninja
  • Comes with Visual Studio, or use winget install --id Kitware.CMake and winget install --id Ninja-build.Ninja

In Visual Studio Code

Open Visual Studio Code from a x64 Native Tools Command Prompt for VS 2022 and use standard IDE commands for building (ctrl+shift+B).

From the command line

This project builds with both the Swift Package Manager (SPM) and CMake. SPM supports running tests, but requires a helper script because it cannot integrate all build steps.

1. Open a x64 Native Tools Command Prompt for VS 2022
2. Refer to the Build and Test workflow for build commands

Architecture

The library consists in two layered modules:

• DotNetMetadata (logical layer): Provides an object model for .NET concepts of assemblies, types and members, including resolution of cross-assembly references, similar to the System.Reflection APIs.
• DotNetMetadataFormat (physical layer): Implements low-level decoding of the .NET portable executable file format and provides a strongly-typed view of the metadata tables, heaps and signatures.

The logical layer can represent a mock mscorlib assembly and its core types to support inspecting .winmd files, which reference an unresolvable mscorlib, Version=255.255.255.255.

Error Handling

The code currently makes liberal use of ! and fatalError, making it unsuitable for some production scenarios. The plan is to progressively transition to throwing errors as needed, and the expectation is that most of the logical layer API will be marked throws, to fail at a fine granularity in the presence of a few pieces of malformed data.