SwiftBindings.Runtime 0.2.0

Swift + ObjC .NET Bindings

A single tool that generates .NET bindings from Swift, Objective-C, or mixed Apple frameworks.

Swift Bindings

Automatically generate C# bindings from compiled Swift libraries. No proxy layers. No Objective-C bridging headers. No manual wrapper code.

Swift Bindings reads the ABI metadata from a compiled Swift framework and produces idiomatic C# that calls directly into the Swift dylib via P/Invoke. The generated bindings handle memory management (ARC), async methods, closures, generics, protocols, and more, so you can consume Swift libraries from .NET the same way you'd consume a NuGet package.

Objective-C Bindings

A full replacement for Objective Sharpie. Ready-to-compile output with no [Verify] cleanup required.

Point the same tool at an Objective-C framework and it parses headers via clang, emits standard ApiDefinition.cs + StructsAndEnums.cs binding definitions, and generates a ready-to-build .csproj — no manual cleanup required. Drop any xcframework and the correct pipeline runs automatically.

For the story behind this project — why it exists, the process of building it entirely with AI tooling, and lessons learned along the way — check out the full write-up on my blog.

Support This Project

This project takes a massive amount of effort to build and maintain, and the tooling used to develop it isn't cheap. If you find it useful, please consider sponsoring the project.

Why This Exists

Apple is moving away from Objective-C. Every year, more frameworks ship as Swift-only with no Objective-C equivalent:

• StoreKit 2 — Swift-only in-app purchase API
• SwiftUI — Swift-only UI framework
• WeatherKit, App Intents, Swift Charts — all Swift-only
• Third-party libraries increasingly drop ObjC support entirely

Without Swift interop, .NET on Apple platforms becomes progressively less accessible each year.

And for the Objective-C frameworks that remain, the de facto binding tool — Objective Sharpie — hasn't been updated for modern Xcode and produces output requiring extensive manual cleanup ([Verify] attributes on every binding).

Swift Bindings automates the entire process:

Traditional approach (Swift):
  Swift API → manual Swift proxy → @objc headers → Objective Sharpie → C# binding
  (significant work, fragile, limited to ObjC-compatible types)

Traditional approach (Objective-C):
  ObjC framework → Objective Sharpie → C# binding
  (numerous [Verify] attributes to review, manual .csproj scaffolding)

Swift Bindings approach (both):
  Any xcframework → SwiftBindings tool → C# binding
  (automated, ready to compile)

Where This Project Comes From

This project is a fork of Microsoft's dotnet/runtimelab (feature/swift-bindings branch) — an experimental effort that established the foundational architecture (ABI JSON parsing, Swift symbol demangling, type database, code emitter) but was never intended as a shipping product. Development went inactive with support limited to basic classes, structs, and simple method signatures.

Since forking, this project has grown from a proof-of-concept into a comprehensive binding generator — 700+ commits and ~300K net new lines of code (7x the original codebase). That breaks down to ~125K lines of production code (generator, runtime, SDK) backed by ~175K lines of tests across 7,000+ test cases. The generator now supports protocols, generics, closures, async, SwiftUI bridging, protocol extensions, existential containers, and much more — validated against 46 real-world libraries (89 framework targets — 55 Swift, 34 ObjC), with select libraries tested end-to-end on .NET apps running on iOS and macOS.

What It Can Do

The generator handles the full breadth of Swift's type system:

• Classes with automatic reference counting (ARC) via SafeHandle, including inheritance hierarchies
• Structs (frozen and non-frozen), enums with associated values, raw types, case construction, and pattern-matched inspection
• Protocols with interface generation, proxy classes, witness table dispatch, and protocol conformance on concrete types
• Protocol extensions — methods from protocol extensions injected onto conforming types, including generic extensions and extensions on foreign types (UIKit, etc.)
• Generics — bound generics, generic enums and classes, unbound type parameters, generic closures
• Async methods via Swift wrapper generation with C# Task<T> / await support, CancellationToken threading, and actor isolation (@MainActor)
• Closures (@convention(c), @escaping) with automatic delegate marshalling, including closures with bound generic arguments and error propagation
• Tuples, operators, subscripts, inout parameters, failable initializers
• Existential containers (any Protocol) as parameters and return values, with concrete-type boxing via IExistentialBoxable
• Type projections — String → string, Array<T> → IReadOnlyList<T>, Set<T> → IReadOnlySet<T>, Dictionary<K,V> → IReadOnlyDictionary<K,V>, Data → byte[], Optional<T> → T?
• Convenience overloads — nint/nuint parameters get int/uint overloads, methods with default parameters get reduced-arity overloads
• SwiftUI Views — automatic UIHostingController bridge with two-way state updates, view modifier chains, and async factory patterns
• XML doc comments — Swift documentation automatically extracted and converted to C# IntelliSense docs

See the full type conversion table and complete feature reference.

Objective-C Support

The generator is also a full replacement for Objective Sharpie for pure Objective-C frameworks. Point it at any xcframework with ObjC headers:

• Parses all public headers via clang -ast-dump=json (uses Xcode's built-in clang)
• Emits standard ApiDefinition.cs + StructsAndEnums.cs binding definitions
• Generates a ready-to-build .csproj — produces a NuGet package compatible with .NET MAUI
• No [Verify] attributes — output compiles without manual review (Sharpie typically requires dozens per library)

Supports protocol patterns ([Protocol, Model], WeakDelegate/Wrap), idiomatic C# enums with prefix stripping, availability attributes, foreign-type categories, designated initializer detection, pointer/out-param mapping, and rich XML doc comments.

Mixed frameworks (Swift + ObjC) are also supported with automatic type-level dedup. Framework type is auto-detected — no flags needed, same dotnet build workflow.

Validated against 34 ObjC framework targets including Realm, Stripe3DS2, SDWebImage, CocoaLumberjack, MBProgressHUD, and the full Firebase/Google SDK family (28 targets).

Real-World Validation

Validated against 46 libraries (89 framework targets — 55 Swift, 34 Objective-C) spanning image loading, payments, animation, networking, document scanning, analytics, and more:

Select libraries (Nuke, Lottie, BlinkID, BlinkID UX, Stripe) have dedicated test apps with end-to-end runtime validation on iOS Simulator in the swift-dotnet-packages repo. Pre-built NuGet packages for popular libraries are coming soon. The generator also validates Nuke across macOS and tvOS targets.

Examples

Async image loading with Nuke:

// Load an image asynchronously
var pipeline = ImagePipeline.Shared;
var request = new ImageRequest("https://example.com/photo.jpg");
UIImage image = await pipeline.ImageAsync(request);

// Check the cache first
ImageContainer? cached = pipeline.CacheValue.CachedImage(request);

Animation playback with Lottie:

// Play with a completion callback and nullable loop mode
var animationView = new LottieAnimationView();
animationView.Animation = myAnimation;
animationView.Play(
    fromProgress: 0.0, toProgress: 1.0,
    loopMode: LottieLoopMode.Loop,
    completion: finished => Console.WriteLine($"Done: {finished}")
);

// Playback control
animationView.Pause();
bool playing = animationView.IsAnimationPlaying;
double progress = animationView.CurrentProgress;

All generated C# — no proxy libraries, no bridging headers, no manual wrapper code.

SwiftUI Interop

SwiftUI Views can't be bound through conventional interop — they rely on opaque return types, property wrappers, and a declarative rendering pipeline with no C# equivalent.

Swift Bindings generates a bridge layer that wraps SwiftUI Views in UIHostingController, exposing them as UIViewController instances that .NET can embed in any UIKit-based layout (including .NET MAUI). This bridge generation is fully automatic — the generator analyzes View initializer parameters and produces the correct interop code for primitives, strings, closures, enums, class references, and async factory patterns. The bridge also supports two-way state updates via Update{Param}() methods, view modifier chains, and multi-level async view hierarchies with cycle detection.

For customization options (bridge hints, constructor selection, import overrides), see the SwiftUI Interop docs.

Getting Started

Requires: macOS, Xcode 26 or later, and .NET 10 SDK with the platform workload for your target (e.g., dotnet workload install ios).

Supported platforms: iOS, macOS, Mac Catalyst, tvOS. The generator, MSBuild SDK, and runtime all support multi-platform targeting — generate bindings for any Apple platform with a single --platform flag or by changing the TFM.

# 1. Install the project template and MSBuild SDK
dotnet new install SwiftBindings.Templates

# 2. Create a binding project (default: iOS; use --platform for others)
dotnet new swift-binding -n MyLibrary.Swift.iOS
# dotnet new swift-binding -n MyLibrary.Swift.macOS --platform macos

# 3. Copy your xcframework into the project directory
cp -r /path/to/MyLibrary.xcframework MyLibrary.Swift.iOS/

# 4. Build — generates bindings and compiles the project
cd MyLibrary.Swift.iOS && dotnet build

# 5. Pack into a NuGet package, then consume in any .NET Apple platform app
dotnet pack
dotnet add package MyLibrary.Swift.iOS

For prerequisites, CLI usage, and a full walkthrough, see the Getting Started guide.

AI-Assisted Binding Creation

A Claude Code skill is available that walks you through the entire binding process — from SPM package or xcframework to a validated NuGet package. It checks prerequisites, builds xcframeworks, diagnoses errors using the latest docs, and optionally reviews the generated binding for completeness.

Claude Code:

# Add the skills marketplace
/plugin marketplace add justinwojo/claude-skills

# Install the skill
/plugin install swift-binding-assistant@justinwojo-claude-skills

Then just ask Claude: "I want to create a Swift binding for [library name]"

Codex / other AI tools: The skill definition is a standalone markdown file (swift-binding-assistant/SKILL.md). Copy its contents into your tool's custom instructions or system prompt to get the same guided workflow.

Working with Swift Package Manager Libraries

Swift Bindings requires a compiled .xcframework as input. If you're working with a library distributed through Swift Package Manager (SPM), you'll need to build it into an xcframework first.

This is intentionally out of scope for Swift Bindings — SPM dependency resolution, multi-platform builds, and ABI-stable framework generation involve a significant amount of complexity that's orthogonal to binding generation. Keeping the concerns separate means each tool can evolve independently.

I maintain a standalone script for this: spm-to-xcframework

It handles the full conversion — resolving the package, building for device and simulator, enabling BUILD_LIBRARY_FOR_DISTRIBUTION for ABI stability, and producing a ready-to-use xcframework:

# Clone the tool
git clone https://github.com/justinwojo/spm-to-xcframework.git

# Build an xcframework from any SPM package
./spm-to-xcframework/spm-to-xcframework https://github.com/kean/Nuke --version 12.0.0

# Then generate bindings as usual
dotnet new swift-binding -n Nuke.Swift.iOS
cp -r Nuke.xcframework Nuke.Swift.iOS/
cd Nuke.Swift.iOS && dotnet build

Documentation

Full documentation is available on the project wiki.

Known Limitations

Swift Bindings targets .NET 10 on Apple platforms, which currently uses the Mono runtime. Mono's JIT compiler has a known defect that causes crashes with CallConvSwift in certain P/Invoke frame types. This only affects Mono JIT builds (iOS/tvOS Simulator) — device builds use NativeAOT and macOS native builds are unaffected. Four transparent workarounds are built into the generator and runtime — generated bindings work correctly without manual intervention.

For full details, see Known Limitations.

Project Status

Swift Bindings is under active development. The core generator, MSBuild SDK, and NuGet packaging are all functional — validated against 46 libraries (89 framework targets — 55 Swift, 34 ObjC) and tested with 7,000+ unit tests and 700+ runtime tests on iOS Simulator and macOS. Multi-platform support (iOS, macOS, Mac Catalyst, tvOS) is built into the generator, SDK, and runtime.

Contributing

The best way to contribute right now is through issue reports — binding errors, feature requests, and bug reports help prioritize the most impactful work. Pull requests are welcome too, but please open an issue first to discuss the change.

See CONTRIBUTING.md for development setup, PR guidelines, and details on the AI-assisted workflow used to build this project.

License

Licensed under the MIT License.

Originally developed by Microsoft Corporation as part of dotnet/runtimelab. Now maintained and actively developed by Justin Wojciechowski.