https://github.com/tristanlabelle/swift-dotnetmetadata
A Swift library for reading .NET metadata files, including WinMD files.
https://github.com/tristanlabelle/swift-dotnetmetadata
Last synced: 6 months ago
JSON representation
A Swift library for reading .NET metadata files, including WinMD files.
- Host: GitHub
- URL: https://github.com/tristanlabelle/swift-dotnetmetadata
- Owner: tristanlabelle
- License: mit
- Created: 2023-05-08T02:39:04.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-24T12:06:40.000Z (over 1 year ago)
- Last Synced: 2024-04-25T12:43:35.320Z (about 1 year ago)
- Language: Swift
- Homepage:
- Size: 556 KB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: Readme.md
- License: License.txt
Awesome Lists containing this project
README
# DotNetMetadata
A Swift library for reading and inspecting .NET metadata, including WinMD files, following the [ECMA-335, Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/) standard. Parsing IL is currently out of scope, but not off the table in the future.
## Example
```swift
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
// 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](.github/workflows/build-and-test.yml) 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.