Meziantou.NET.Sdk.Razor 1.0.161

Meziantou.NET.Sdk

MSBuild SDK that helps standardize build and quality settings across repositories. It provides:

• Opinionated defaults and naming conventions for .NET projects
• Best practices for build, CI, and test workflows
• A static analysis baseline with Roslyn analyzers
• Set ContinuousIntegrationBuild based on the context
• dotnet test features
  • xUnit.net v3 and Microsoft Testing Platform (MTP) by default
  • Dump on crash or hang
  • Loggers when running on GitHub
  • Annotations and job summary when running on GitHub Actions
  • Disable Roslyn analyzers to speed up build
• Relevant NuGet packages based on the project type

Blog post: Creating a custom MSBuild SDK to reduce boilerplate in dotnet projects

Usage

Method 1

To use it, create a global.json file at the solution root with the following content:

{
  "sdk": {
    "version": "9.0.304"
  },
  "msbuild-sdks": {
    "Meziantou.NET.Sdk": "1.0.16",
    "Meziantou.NET.Sdk.BlazorWebAssembly": "1.0.16",
    "Meziantou.NET.Sdk.Razor": "1.0.16",
    "Meziantou.NET.Sdk.Test": "1.0.16",
    "Meziantou.NET.Sdk.Web": "1.0.16",
    "Meziantou.NET.Sdk.WindowsDesktop": "1.0.16"
  }
}

And reference the SDK in your project file:

<Project Sdk="Meziantou.NET.Sdk">
</Project>

Method 2

You can the SDK by specifying the version inside the csproj file:

<Project Sdk="Meziantou.NET.Sdk/1.0.16">
</Project>

Method 3

<Project Sdk="Microsoft.NET.SDK">
    <Sdk Name="Meziantou.NET.Sdk" Version="1.0.16" />
</Project>

File-based apps (.NET 10+)

You can use the SDK with file-based apps using the #:sdk directive:

#:sdk Meziantou.NET.Sdk@1.0.16
Console.WriteLine("Hello from a file-based app!");

Then run with:

dotnet run Program.cs

You can also use it as an additional SDK alongside Microsoft.NET.Sdk:

#:sdk Microsoft.NET.Sdk
#:sdk Meziantou.NET.Sdk@1.0.16
Console.WriteLine("Hello!");

Build configuration properties

Set these properties in your project file or a directory-level props file. Unless stated otherwise, defaults apply only when the property is empty.

General build

Package validation and auditing

Banned symbols and analyzers

The SDK also blocks selected NuGet packages by default:

• YamlDotNet (use Meziantou.Framework.Yaml)
• CliWrap (use Meziantou.Framework.ProcessWrapper)
• Testcontainers (use Meziantou.Framework.TemporaryContainers)
• Meziantou.Xunit.ParallelTestFramework (use the built-in parallelization of xunit.v3)
• Meziantou.Xunit.v3.ParallelTestFramework (use the built-in parallelization of xunit.v3)

Web SDK and containers

Packaging metadata

npm restore

Testing

A project using Meziantou.NET.Sdk.Test needs no PackageReference to run tests:

<Project Sdk="Meziantou.NET.Sdk.Test">
</Project>

public class Tests
{
    [Fact]
    public void Test1() { }
}

It gets xUnit.net v3 on Microsoft Testing Platform, a TRX report, crash and hang dumps, code coverage on CI, and GitHub Actions annotations and job summary when running on GitHub Actions. Add the following to global.json so dotnet test runs in MTP mode:

{
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}

dotnet test only reports failures by default. Use dotnet test --output Detailed to also list the tests that passed — the option belongs to dotnet test itself, so it cannot be set from the project file.

To use another test framework, reference it: the default framework is not added when the project already references xunit, xunit.v3*, TUnit, MSTest, or NUnit. Set EnableDefaultTestFramework to false for full control. Only Microsoft Testing Platform is supported, so the framework must run on it: the SDK never adds Microsoft.NET.Test.Sdk and configures no VSTest setting.

The assertions come from Meziantou.Framework.Assertions instead of xUnit.net. The SDK adds the package and generates the global using Assert = Meziantou.Framework.Assertions.Assert; alias, so Assert refers to it in any test — a using alias takes precedence over the namespaces imported in the same scope, so it wins over the global using Xunit; directive:

[Fact]
public void Sample() => Assert.HasCount(2, new[] { 1, 2 });

Only the meaning of Assert changes: the assertions of the test framework stay available under their full name, such as Xunit.Assert. This happens when the SDK adds the default test framework itself and the project targets .NET 10 or later, as the package supports no older framework. Set EnableMeziantouAssertions to true to add it whatever the referenced packages and the target framework are, or to false to opt out and keep the assertions of the test framework:

<PropertyGroup>
  <EnableMeziantouAssertions>false</EnableMeziantouAssertions>
</PropertyGroup>

xUnit.net v3 runs test collections in parallel, but the tests inside a collection run one after the other. When the project resolves xUnit.net v3 4.0 or later, the SDK generates a source file that opts the whole assembly into full parallelization:

[assembly: Xunit.v3.Parallelization(Mode = Xunit.Sdk.ParallelMode.All)]

Tests that share mutable state with another test of the same class must therefore be synchronized, or be moved to a collection that disables parallelization. Set EnableXunitFullParallelization to false to not generate the file at all, which is also required when the assembly already declares the attribute itself, as the compiler reports CS0579 for the duplicate:

<PropertyGroup>
  <EnableXunitFullParallelization>false</EnableXunitFullParallelization>
</PropertyGroup>

Set XunitParallelizationMode to generate the attribute with another Xunit.Sdk.ParallelMode value: None (no parallelization at all), Collections (the xUnit.net default: only test collections run in parallel) or All (the SDK default). Setting the property also generates the file whatever the resolved references are, like EnableXunitFullParallelization set to true:

<PropertyGroup>
  <XunitParallelizationMode>None</XunitParallelizationMode>
</PropertyGroup>

When the project references xUnit.net v3, the SDK also generates a source file with static helpers and a global using static directive for them, so TestContext.Current.CancellationToken can be written as XunitCancellationToken in any test:

[Fact]
public async Task Sample() => await httpClient.GetAsync("https://example.com", XunitCancellationToken);

The class is partial, so the project can declare another part of it to add its own helpers, which are then usable without any using directive too.

Set EnableXunitStaticHelpers to false to opt out, which is also required when the project already declares a non-partial Meziantou.NET.Sdk.Test.XUnitStaticHelpers type, as the compiler reports CS0260 for the missing partial modifier:

<PropertyGroup>
  <EnableXunitStaticHelpers>false</EnableXunitStaticHelpers>
</PropertyGroup>

The SDK also defines the XUNIT_ENTRYPOINT_DISABLE_WARNINGS compilation constant in every test project:

#if XUNIT_ENTRYPOINT_DISABLE_WARNINGS
// ...
#endif

Set EnableXunitEntryPointDisableWarnings to false to not define it:

<PropertyGroup>
  <EnableXunitEntryPointDisableWarnings>false</EnableXunitEntryPointDisableWarnings>
</PropertyGroup>