Canonical guidance for AI coding agents working in this repository. This is the single
source of truth; CLAUDE.md and .github/copilot-instructions.md point here.
A UniFFI C# bindings generator. It takes UniFFI component definitions (UDL files or proc-macro
libraries) and generates C# code that calls into Rust shared libraries via FFI. Standalone from the
main uniffi-rs repository.
Current version: 0.11.0+v0.31.0 (generator v0.11, targeting uniffi-rs v0.31.0). Requires Rust 1.88+.
There is no cargo test integration. Tests are xUnit v3 tests (running on Microsoft.Testing.Platform)
that execute against generated bindings.
# Full pipeline (build → generate → test)
make all
# Individual steps
./build.sh # cargo build of bindgen CLI + fixture shared library
./generate_bindings.sh # generate C# bindings into dotnet-tests/UniffiCS/gen/
./test_bindings.sh # dotnet test on dotnet-tests/- Tests run on xUnit v3 via Microsoft.Testing.Platform (MTP) —
dotnet-tests/global.jsonsets"runner": "Microsoft.Testing.Platform", andUniffiCS.BindingTests.csprojreferencesxunit.v3.mtp-v2with<OutputType>Exe</OutputType>and<UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>. UniffiCS.BindingTeststargets net9.0 (downgraded from net10.0 in commit 6395dea until the CI image is updated).- The generated bindings library
UniffiCSdual-targets netstandard2.0 + net8.0.
xUnit v3 on MTP uses framework-specific filter flags (not the VSTest --filter expression). Pass MTP
arguments after --:
dotnet test dotnet-tests -- --filter-class "*TestArithmetic*"Other MTP filter flags: --filter-method, --filter-namespace, --filter-trait "name=value", and
their --filter-not-* negations; --filter-query for the path-segment query language.
Note: on the .NET 10 SDK the legacy VSTest bridge that
dotnet testused is removed, so the command above requires opting into the new dotnet-test experience (or running against a .NET 9 SDK, which CI uses). The test project is an MTP executable, so you can also run the built binary directly with the same filter flags, e.g.dotnet dotnet-tests/UniffiCS.BindingTests/bin/Debug/net9.0/UniffiCS.BindingTests.dll --filter-class "*TestArithmetic*".
./docker.sh drops you into an interactive shell in the
ghcr.io/nordsecurity/uniffi-bindgen-cs-test-runner:v0.2.1 container with the repo mounted at
/mounted_workdir. From that shell, run the pipeline:
./docker.sh # opens the container shell
# then, inside the container:
make allUDL / compiled library → [uniffi_bindgen parses → ComponentInterface] → [gen_cs + Askama templates] → single .cs file per component
bindgen/src/gen_cs/— Rust modules implementing theCodeTypetrait for each UniFFI type.mod.rsis the orchestrator containingCsWrapper,TypeRenderer,CsCodeOracle, andConfig.bindgen/templates/— Askama templates (.csfiles) that produce the generated C# code. Each template maps to a UniFFI type or helper construct. Template syntax is configured inbindgen/askama.toml.bindgen/src/gen_cs/filters.rs— Template filters bridging Rust codegen with Askama rendering (type_name,ffi_converter_name,lower_fn,lift_fn, etc.).fixtures/— Rust crates defining test fixture libraries with UniFFI interfaces, compiled into a single shared library (uniffi_fixtures).dotnet-tests/UniffiCS.BindingTests/— xUnit tests exercising generated bindings against the fixture library.
Each UniFFI type has a Rust module in gen_cs/ implementing the CodeType trait (type_label,
canonical_name, ffi_converter_name, literal). The corresponding Askama template in
bindgen/templates/ renders the C# FFI converter and helper code. The main wrapper template
(wrapper.cs) and type dispatcher (Types.cs) orchestrate the output.
Generated code supports both .NET Framework 4.6.1+ and .NET 8.0+, with conditional compilation
(NET8_0_OR_GREATER) for platform differences like LibraryImport vs DllImport.
- Naming: C# output uses
UpperCamelCasefor types/methods,lowerCamelCasefor parameters. Conversions via theheckcrate. - Configuration: TOML under
[bindings.csharp]— seedocs/CONFIGURATION.mdforcdylib_name,custom_types,namespace,access_modifier,rename, etc. - DCO sign-off: All commits require
git commit -s. - Adding a fixture: Create a Rust crate in
fixtures/, add it to thefixtures/Cargo.tomlworkspace, and write tests indotnet-tests/UniffiCS.BindingTests/. - Upgrading uniffi-rs: Follow
docs/VERSION_UPGRADE.md— verify C ABI compatibility ofRustBuffer,RustCallStatus,ForeignBytes, and FFI converters. - Versioning: Tags use
vX.Y.Z+vA.B.Cformat. Updatebindgen/Cargo.toml,README.md, andCHANGELOG.mdon release (seedocs/RELEASE.md). - Debugging hanging tests: Set
diagnosticMessagestotrueindotnet-tests/UniffiCS.BindingTests/xunit.runner.json.