Allors.Immersive.Winforms 2.1.11-preview

Prefix Reserved
This is a prerelease version of Allors.Immersive.Winforms.
dotnet add package Allors.Immersive.Winforms --version 2.1.11-preview
                    
NuGet\Install-Package Allors.Immersive.Winforms -Version 2.1.11-preview
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Allors.Immersive.Winforms" Version="2.1.11-preview" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Allors.Immersive.Winforms" Version="2.1.11-preview" />
                    
Directory.Packages.props
<PackageReference Include="Allors.Immersive.Winforms" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Allors.Immersive.Winforms --version 2.1.11-preview
                    
#r "nuget: Allors.Immersive.Winforms, 2.1.11-preview"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Allors.Immersive.Winforms@2.1.11-preview
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Allors.Immersive.Winforms&version=2.1.11-preview&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Allors.Immersive.Winforms&version=2.1.11-preview&prerelease
                    
Install as a Cake Tool

Immersive

Allors.Immersive Allors.Immersive.Attributes Allors.Immersive.MSBuild Allors.Immersive.Tool Allors.Immersive.Winforms

Immerse a library inside another library.

Immersive is an IL weaver for .NET. After a project compiles, it rewrites the project's assembly so that the classes and methods it uses from one library are replaced by substitutes from another assembly. The source code does not change, and a Release build can stay exactly as compiled.

Allors uses it to test desktop applications. The Allors.Immersive.Winforms library substitutes the Windows Forms controls, forms, dialogs and message boxes with subclasses that a test can find by name and drive, while the application runs its real forms. A library for Avalonia is in the repository as well.

Documentation

The documentation is written for users and for maintainers. Start with Getting started, a tutorial that builds three small projects and weaves one of them, and How weaving works. Agent instructions are in AGENTS.md.

Example

A library has a dialog, and an application derives from it:

// The referenced library
namespace Desktop;

public class Dialog
{
    public string ShowDialog() => "A window appeared on screen";
}
// The immerse assembly: substitutes marked with attributes, plus a marker class
namespace Desktop.Testing;

using Allors.Immersive.Attributes;

public class Marker { }

[SubstituteClass]
public class Dialog : Desktop.Dialog
{
    [SubstituteMethod(typeof(Desktop.Dialog), "ShowDialog")]
    public string ShowDialogSubstitute() => "No window: the substitute answered";
}
// The application: unchanged, apart from the marker that names the immerse assembly
public class MainForm : Desktop.Dialog
{
    public string Run() => this.ShowDialog();
}

#if DEBUG
public class ImmersiveMarker : Desktop.Testing.Marker { }
#endif

After immerse App.dll, MainForm derives from the substitute Dialog and Run() returns No window: the substitute answered. The tutorial shows every step and its output.

Install

The packages are published as previews from main, so --prerelease is required.

dotnet add package Allors.Immersive.Attributes --prerelease   # in the immerse assembly
dotnet tool install Allors.Immersive.Tool --prerelease         # the immerse command
dotnet add package Allors.Immersive.Winforms --prerelease      # substitutes for Windows Forms
dotnet add package Allors.Immersive --prerelease               # the weaving engine, as an API

Weave the compiled assembly after each build, for example from a target in the project file:

<Target Name="Immerse" AfterTargets="Build" Condition="'$(IsCrossTargetingBuild)' != 'true'">
  <Exec Command="dotnet immerse &quot;$(TargetPath)&quot; -v" />
</Target>

The condition keeps the target out of the outer build of a project with several target frameworks, where $(TargetPath) is empty.

Allors.Immersive.MSBuild packages the weaver as an MSBuild task, but 2.1.10-preview, the version published when this was checked on 2026-10-18, fails a fresh dotnet build, because the task runs before the output assembly exists. Use the tool until a corrected version ships; see Run the weaver.

Building

The project uses Nuke as its build system and needs Windows, the .NET 10 SDK and the .NET Framework 4.8 developer pack.

./build.cmd Compile        # restore and build
./build.cmd Test           # run the engine and Windows Forms tests
./build.cmd Pack           # create NuGet packages in output/
./build.cmd Clean Compile  # clean, then build

Build and release describes the build, the test suites, versioning and publication.

Solution structure

Project Description
src/Allors.Immersive The weaving engine, built on dnlib
src/Allors.Immersive.Attributes SubstituteClassAttribute and SubstituteMethodAttribute
src/Allors.Immersive.MSBuild MSBuild task that invokes the weaver
src/Allors.Immersive.Tool The immerse command, a .NET tool
src/Allors.Immersive.Winforms Windows Forms substitutes, testers and session
src/Allors.Immersive.Avalonia Avalonia substitutes, testers and session; built, not yet packaged
test/Allors.Immersive.AssemblyReferenced Test fixture: the referenced library
test/Allors.Immersive.AssemblyToImmerse Test fixture: the substitutes
test/Allors.Immersive.AssemblyToProcess Test fixture: the target assembly to weave
test/Allors.Immersive.Tests Engine tests on the woven fixture
test/Allors.Immersive.Winforms.AssemblyToProcess, test/Allors.Immersive.Winforms.Tests Windows Forms fixture application and tests
test/Allors.Immersive.Avalonia.AssemblyToProcess, test/Allors.Immersive.Avalonia.Tests Avalonia fixture application and tests
docs The documentation website

Licence

LGPL-3.0-only

Product Compatible and additional computed target framework versions.
.NET net10.0-windows7.0 is compatible. 
.NET Framework net48 is compatible.  net481 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.1.11-preview 71 10/19/2026
2.1.10-preview 129 2/12/2026
2.1.9-preview 108 2/11/2026