Build environment
- Install .NET SDK 10.0 or newer. Metalama 2027.0 no longer runs on the .NET 8 or the .NET 9 SDK. If your IDE bundles an older .NET SDK, install the .NET 10 SDK separately.
- Metalama is tested on Windows (x64), Ubuntu (x64), and macOS (ARM). For a list of tested platforms, see https://github.com/metalama/Metalama.Tests.DotNetSdk/.
IDEs
Metalama integrates with Roslyn, making it compatible with any Roslyn-based IDE.
| IDE | Earliest supported version | Design-time correctness | Code fixes | Additional UI features |
|---|---|---|---|---|
| Visual Studio 2026 with Visual Studio tooling | LTSC baseline of November 2026 | Yes | Yes | Transformed code diff, info bar, syntax highlighting |
| Visual Studio 2026 without Visual Studio tooling | LTSC baseline of November 2026 | Yes | Yes | |
| Rider | Current release | Yes | Yes | |
| Visual Studio Code (C# Dev Kit) | Current release | Yes | Yes |
Visual Studio 2022 is no longer supported. Version 17.14, the last version of Visual Studio 2022, leaves mainstream support in January 2027. If you can't move to Visual Studio 2026, use Metalama 2026.1, which is a long-term support (LTS) release.
Note
Visual Studio Tools for Metalama isn't required but is highly recommended.
Target frameworks
Only SDK-style projects are supported.
Your projects can target any framework that supports .NET Standard 2.0, including:
| Framework | Versions | Testing status |
|---|---|---|
| .NET | 10.0, 11.0 | Tested |
| .NET Framework | 4.8.1 | Tested |
| .NET Framework | 4.8 | Untested |
| MAUI | Tested | |
| MAUI Blazor | Tested | |
| Blazor WebAssembly | Tested | |
| .NET Core | 2.0 or later | Untested |
| .NET | 5.0 to 9.0 | Untested |
| Mono | 5.4 or later | Untested |
| Xamarin.iOS | 10.14 or later | Untested |
| Xamarin.Mac | 3.8 or later | Untested |
| Xamarin.Android | 8.0 or later | Untested |
| Universal Windows Platform | 10.0.16299 or later | Untested |
Untested platforms should work because of .NET Standard compatibility, but we don't test them in our continuous integration builds.
Warning
Metalama.Patterns.Wpf is the one exception. It ships a net472 and a net10.0-windows asset and no .NET Standard asset, so a WPF application targeting .NET 8 or .NET 9 has no compatible asset. Such an application must move to .NET 10 to use that package.
Projects targeting .NET Framework 4.7.2 can still use Metalama, because its packages ship a net472 asset, but .NET Framework 4.7.2 is no longer a supported runtime. Problems that are specific to it won't be fixed. Upgrading the runtime to .NET Framework 4.8 is an in-place update that doesn't require you to change the target framework of your projects.
The build reports a warning when your project, your .NET SDK, or your Visual Studio version is outside the supported set. See The supported platform check in MSBuild properties and environment variables.
For a detailed list of tested target frameworks, https://github.com/metalama/Metalama.Tests.DotNetSdk/.
Synchronizing versions of Metalama, Visual Studio, and .NET SDK
Metalama includes a fork of Roslyn, which comes with Visual Studio. This raises the question of whether you need to synchronize updates of Metalama and your IDEs.
Note
Even if you're not using Visual Studio, your IDE is still bound to a specific version of Roslyn. Roslyn is a part of the Visual Studio product family. Therefore, the support and versioning policies of your IDE are linked to those of Visual Studio.
To avoid versioning issues, follow these guidelines:
- Update your IDE or .NET SDK at any time without impacting Metalama projects, as long as you don't start using new C# features. Simply updating Visual Studio won't cause issues.
- Before using new C# features in a Metalama project, update Metalama to a version that supports the new C# version. Otherwise, your code may fail to compile.
- Use a version of Visual Studio that's under active mainstream support by Microsoft. When a version falls out of support, update to a supported version within three months. Unsupported versions limit you to language features of the last supported C# version below the version you're using, potentially leaving you stuck with an unsupported Metalama version.
We add support for new Roslyn versions within three weeks of their stable release and remove support for obsolete versions no sooner than three months after they fall out of mainstream support by Microsoft.
Warning
We're dedicated to keeping Metalama forward-compatible with future .NET SDK and Visual Studio releases. While we actively address compatibility issues, we can't guarantee that new updates to .NET or Visual Studio won't introduce breaking changes. For a smooth experience, keep your maintenance subscription current and update Metalama alongside your development environment.
For more information on Visual Studio support policies, see Visual Studio Product Lifecycle and Servicing and Visual Studio Channels and Release Rhythm.
Here's the rationale behind these guidelines:
Note
The Metalama.Compiler package replaces the C# compiler included in Visual Studio or the .NET SDK. Your code builds against the version of Roslyn that Metalama was built for, regardless of your installed IDE or .NET SDK version. To avoid incompatibilities after .NET SDK updates, Metalama.Compiler also includes a backup copy of all Roslyn analyzers normally included in the .NET SDK. If incompatibility occurs, these backup copies replace the ones from your locally installed .NET SDK.