Allors.Immersive.Attributes
2.1.11-preview
Prefix Reserved
dotnet add package Allors.Immersive.Attributes --version 2.1.11-preview
NuGet\Install-Package Allors.Immersive.Attributes -Version 2.1.11-preview
<PackageReference Include="Allors.Immersive.Attributes" Version="2.1.11-preview" />
<PackageVersion Include="Allors.Immersive.Attributes" Version="2.1.11-preview" />
<PackageReference Include="Allors.Immersive.Attributes" />
paket add Allors.Immersive.Attributes --version 2.1.11-preview
#r "nuget: Allors.Immersive.Attributes, 2.1.11-preview"
#:package Allors.Immersive.Attributes@2.1.11-preview
#addin nuget:?package=Allors.Immersive.Attributes&version=2.1.11-preview&prerelease
#tool nuget:?package=Allors.Immersive.Attributes&version=2.1.11-preview&prerelease
Immersive
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 "$(TargetPath)" -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 | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Framework | net48 is compatible. net481 was computed. |
-
.NETFramework 4.8
- No dependencies.
-
net10.0
- No dependencies.
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Allors.Immersive.Attributes:
| Package | Downloads |
|---|---|
|
Allors.Immersive.Winforms
WinForms testing library for Allors.Immersive IL weaver. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2.1.11-preview | 70 | 10/19/2026 |
| 2.1.10-preview | 129 | 2/12/2026 |
| 2.1.9-preview | 107 | 2/11/2026 |