WrapGod

Stop rewriting code when libraries change. WrapGod generates type-safe wrapper interfaces over third-party .NET APIs so your application code never touches vendor types directly. Upgrade, swap, or support multiple versions — without refactoring a single line.

---

The Problem

Every .NET team has been burned by this: you upgrade a NuGet package and half your solution lights up red. Method signatures changed, types moved namespaces, a property you relied on quietly disappeared. Your team spends the next two weeks hunting down every call site, updating tests, and hoping nothing slips through to production.

This isn't a one-time pain — it's a recurring tax. Every third-party library your codebase touches is a liability. Serilog, AutoMapper, MediatR, your HTTP client, your ORM. Each one has its own release cadence, its own breaking-change philosophy, and its own upgrade timeline. Multiply that across microservices and a routine upgrade becomes a multi-sprint project.

The root cause is simple: your application code is coupled directly to vendor APIs. Every new JsonSerializer(), every ILogger.LogInformation() call, every extension method — they're all hard dependencies on someone else's type system. When that type system changes, your code breaks.

How WrapGod Solves It

WrapGod generates thin wrapper interfaces and facade classes between your code and vendor libraries. Your application talks to IWrappedJsonSerializer instead of JsonSerializer directly. When the vendor ships a breaking change, you regenerate the wrappers — your code stays untouched.

This isn't another abstraction layer you write and maintain by hand. WrapGod extracts the full public API surface of any .NET assembly into a manifest, then a Roslyn source generator emits the wrapper code at build time. The wrappers delegate straight through to the real types — zero runtime overhead, zero boilerplate to maintain.

The entire pipeline runs as part of your normal dotnet build. You configure once, and the build system handles everything. Upgrading a vendor library is changing a version number.

Quick Start

The fastest path from nothing to generated wrappers:

dotnet add package WrapGod.Generator
dotnet add package WrapGod.Analyzers

Add your manifest as an AdditionalFile in your .csproj:

<ItemGroup>
  <AdditionalFiles Include="vendor.wrapgod.json" />
</ItemGroup>

Then build:

dotnet build  # wrappers generated automatically

For the full walkthrough — extracting manifests, configuring rules, running analyzers — see the Quick Start Guide.

CLI

Command	Description
wrap-god extract	Extract a manifest from any .NET assembly
wrap-god analyze	Detect direct vendor usage in your codebase
wrap-god diff	Compare two manifest versions and report breaking changes
wrap-god merge	Merge multiple version manifests into one
wrap-god migrate generate	Generate a draft migration schema from two library versions (NuGet or local DLLs)
wrap-god migrate apply	Apply a migration schema to a codebase (supports --dry-run)
wrap-god migrate status	Report migration progress from the state file
wrap-god migrate verify	Build the project and correlate compiler diagnostics to migration rules

Install: dotnet tool install -g WrapGod.Cli

See CLI Reference for full usage and options.

Migration Engine

When a library you depend on ships breaking changes, WrapGod can automate the bulk of the upgrade work. The Migration Engine takes a migration schema — a JSON file describing what changed (renames, moves, removals, restructurings) — and applies it to your codebase using Roslyn syntax rewriting. No compilation required: it handles broken code, preserves whitespace and comments, and records everything it touched so re-runs are safe.

# Generate a draft schema from two NuGet versions
wrap-god migrate generate --package MudBlazor --from 6.0.0 --to 7.0.0

# Preview changes (dry-run)
wrap-god migrate apply \
  --schema mudblazor.6.0.0-to-7.0.0.wrapgod-migration.json \
  --project-dir ./src \
  --dry-run

# Apply for real
wrap-god migrate apply \
  --schema mudblazor.6.0.0-to-7.0.0.wrapgod-migration.json \
  --project-dir ./src

# Correlate any build errors to the rules that caused them
wrap-god migrate verify \
  --schema mudblazor.6.0.0-to-7.0.0.wrapgod-migration.json

The engine supports 11 rule kinds covering everything from simple renames to method splits, parameter-object extractions, and static member moves. Library authors can ship migration schemas alongside their NuGet packages so consumers can upgrade with a single command.

See Migration Engine documentation for the full guide.

The Pipeline

WrapGod works in four stages, all wired into your build automatically:

  Assembly DLL(s)
       |
       v
  [ Extract ]  ──  Interrogate public API surface  ──>  ApiManifest (JSON)
       |
       v
  [ Configure ]  ──  JSON / Attributes / Fluent DSL  ──>  Wrapper rules
       |
       v
  [ Generate ]  ──  Roslyn incremental source gen  ──>  IWrapped*.g.cs + *Facade.g.cs
       |
       v
  [ Analyze ]  ──  Detect direct vendor usage  ──>  WG2001/WG2002 diagnostics + auto-fixes

Extract reads any .NET assembly and produces a complete JSON manifest of its public API surface — types, methods, properties, events, version metadata. Configure lets you define wrapper rules through JSON config files, C# attributes ([WrapType], [WrapMember]), or a fluent DSL. Generate is a Roslyn incremental generator that emits IWrapped{Type} interfaces and {Type}Facade delegating classes at build time. Analyze catches any direct usage of wrapped vendor types and offers one-click code fixes to migrate call sites.

Compatibility Modes

Mode	What it does	When to use it
LCD	Lowest common denominator — generates wrappers using only the API surface shared across all extracted versions	Maximum portability across version ranges
Targeted	Pinned to a single version's API surface	You target one specific vendor version
Adaptive	Runtime version guards for members that differ between versions	Multi-version deployments where different services run different versions

See Compatibility Modes for configuration details.

Examples

Example	What it shows
WorkflowDemo	End-to-end pipeline: extract, configure, generate, analyze, fix
Serilog/NLog	Bidirectional logging framework migration with parity tests
AutoMapper/Mapster	Bidirectional object-mapping migration with parity tests
EF Core/Dapper	Service-boundary ORM migration with parity tests
MediatR/MassTransit	Mediator pattern migration with parity tests
NuGet Version Matrix	Version-divergence packs with compatibility reports and CI drift guards

Run the workflow demo:

dotnet run --project examples/WrapGod.WorkflowDemo/WrapGod.WorkflowDemo.csproj

See examples/README.md for the full catalog.

Documentation

• Quick Start Guide — end-to-end onboarding walkthrough
• CLI Reference — command-line tool usage and options
• MSBuild Integration — zero-touch build automation
• Manifest Format — schema, type/member nodes, version metadata
• Configuration Guide — JSON, attributes, fluent DSL, merge precedence
• Compatibility Modes — LCD, Targeted, and Adaptive modes
• Analyzer Diagnostics — WG2001, WG2002, code fixes, suppression
• Migration Engine — automated code migration: all 11 rule kinds, consumer workflow, authoring guide
  • Applying Migrations — consumer workflow: dry-run, apply, status, verify
  • Authoring a Migration Schema — guide for library maintainers
  • Migration Schema Reference — JSON format and all rule kinds
  • Migration Engine Internals — architecture, lifecycle, extension points
• Migration Playbook — strategy selection, authoring mappings, safety model
• Architecture — pipeline internals and design decisions
• Engineering — SDK, build conventions, contribution guidelines
• Feature Completeness Audit — implementation/test/documentation status matrix

Solution Structure

Project	Description
WrapGod.Abstractions	Public attributes ([WrapType], [WrapMember]) and configuration contracts
WrapGod.Manifest	Manifest schema, serialization, JSON config loader, attribute reader, merge engine
WrapGod.Extractor	Assembly interrogation, single- and multi-version manifest extraction
WrapGod.Generator	Roslyn incremental source generator for wrapper interfaces and facades
WrapGod.TypeMap	Type mapping contracts, planner, and mapper emitter
WrapGod.Analyzers	Roslyn diagnostics (WG2001, WG2002) and automatic code fixes
WrapGod.Fluent	Fluent configuration DSL
WrapGod.Cli	Command-line tool (wrap-god extract, wrap-god analyze, wrap-god diff)
WrapGod.Targets	MSBuild targets for zero-touch build integration
WrapGod.Runtime	Optional runtime helpers and adapters
WrapGod.Tests	Unit, integration, and snapshot tests

Contributing

Contributions are welcome. See ENGINEERING.md for build setup, coding conventions, and the test strategy. The project uses .NET 10 SDK and targets net10.0.

Open an issue first for anything beyond trivial fixes — it helps coordinate effort and avoids wasted work.

License

MIT — Copyright (c) 2025-2026 Jerrett Davis