skip to content

Which dotnet new template creates an xunit.v3 test project, and why does the .NET SDK's own xunit template not do so?

level: juniorimportance: should knowfreq 38%

answer

  1. the SDK template still targets v2
  2. template pack xunit.v3.templates
  3. short name xunit3
  4. --test-runner mtp-v2 or vstest
  5. --framework defaults to net8.0

basics

~10 s

The xunit3 template from the xunit.v3.templates package creates an xunit.v3 project. The SDK's built-in dotnet new xunit template still produces a v2 project with Microsoft.NET.Test.Sdk, xunit, xunit.runner.visualstudio and coverlet.collector.

solid answer

~40 s

The .NET SDK ships its own `xunit` template, and it still writes an xUnit.net v2 project referencing `Microsoft.NET.Test.Sdk`, `xunit`, `xunit.runner.visualstudio` and `coverlet.collector`. The v3 template is maintained by the xUnit.net project in the `xunit.v3.templates` package, under the short name `xunit3`. It generates an executable project (`<OutputType>Exe</OutputType>`) with nullable reference types and implicit usings on, a global `<Using Include="Xunit" />`, an `xunit.runner.json` copied to the output, and a reference to `xunit.v3.mtp-v2`. Its options are `--framework` (`net472`, `net48`, `net481`, `net8.0` by default, `net9.0`, `net10.0`), `--test-runner` (`mtp-v2` or `vstest`, which swaps in `xunit.v3.mtp-off` with the VSTest packages), `--command-line` (`xunit` or `mtp`, the experience for `dotnet run`), `--native-aot` for net9.0 and net10.0, and `--no-restore`. The same package also contains `xunit3-extension` for extension libraries.

code

bash · 5 lines
bash
# create a v3 project for the ticketing library on .NET 10 (template pack already installed)
dotnet new xunit3 -o tests/Ticketing.Tests --framework net10.0

# the same, but staying on VSTest
dotnet new xunit3 -o tests/Ticketing.Tests --framework net10.0 --test-runner vstest

go deeper

for a junior

Remember: dotnet new xunit is still v2; use the xunit3 template from xunit.v3.templates for a v3 project.

for a middle

Explain what xunit3 generates and its options (framework, test runner, command line, Native AOT).

for a senior

Catch v2 projects created by habit in review, and choose template options that match the CI's test platform.

for a principal

Standardise project scaffolding across teams so every new test project starts on the intended framework and platform.

## Two templates with similar names A developer who types `dotnet new xunit` on a .NET 10 machine gets a working test project, but an **xUnit.net v2** one. That template ships with the .NET SDK, and the project it creates is the classic v2 shape: four package references and an external runner. | | SDK's `xunit` template | `xunit3` from `xunit.v3.templates` | |---|---|---| | xUnit.net version | v2 | v3 (4.x packages) | | Framework packages | `xunit`, `xunit.runner.visualstudio` | `xunit.v3.mtp-v2` (default) | | Test platform package | `Microsoft.NET.Test.Sdk` | none by default; added for `vstest` | | Coverage | `coverlet.collector` | not added | The v3 template is maintained by the xUnit.net project itself and distributed as the template pack `xunit.v3.templates`; once installed, `dotnet new xunit3` creates the project. The same pack provides `xunit3-extension` for libraries of custom attributes, fixtures or runners. ## What xunit3 generates The default project: - `<OutputType>Exe</OutputType>`, `<Nullable>enable</Nullable>` and `<ImplicitUsings>enable</ImplicitUsings>`; - a target framework of `net8.0` unless `--framework` says otherwise; - a global `<Using Include="Xunit" />`, so test files need no `using Xunit;`; - `xunit.runner.json` with a `$schema` line, copied to the output folder; - one package reference, `xunit.v3.mtp-v2`; - a sample `UnitTest1` class with one `[Fact]`. For .NET Framework targets it also sets `<LangVersion>10.0</LangVersion>` so nullable annotations and implicit usings work. ## The template's options - `--framework`: `net472`, `net48`, `net481`, `net8.0` (default), `net9.0` or `net10.0`. - `--test-runner`: `mtp-v2` (default) or `vstest`. The `vstest` choice replaces the reference with `xunit.v3.mtp-off` plus `Microsoft.NET.Test.Sdk` and `xunit.runner.visualstudio`. - `--command-line`: `xunit` (default) or `mtp`, choosing whether `dotnet run` presents xUnit.net's native command line or Microsoft.Testing.Platform's. Choosing `mtp` adds `<UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>`. - `--native-aot`: available for `net9.0` and `net10.0`; it sets `PublishAot` and references `xunit.v3.aot.mtp-v2`. - `--no-restore`: skip the automatic restore after creation. ## Interaction with the SDK's test runner setting With Microsoft.Testing.Platform, the template does two more things. For frameworks other than `net10.0` it emits `TestingPlatformDotnetTestSupport` so older SDKs route `dotnet test` correctly. It also runs a post-action that creates or updates a repository-level `global.json` to select Microsoft.Testing.Platform as the test runner for the .NET 10 SDK. How that `global.json` setting works is SDK configuration, a separate topic; the practical point is to commit the generated file with the project. ## The extension template `xunit3-extension`, from the same pack, scaffolds a library for extension code: custom data attributes, fixtures shared across test projects, orderers or reporters. Such a library is not a test project, so it references `xunit.v3.extensibility.core` rather than `xunit.v3` and stays a class library. Keeping extension code in its own project lets several test executables share it. ## After creating the project 1. Add a project reference to the code under test, here the ticketing library. 2. Keep the generated `xunit.runner.json`; it is the place for settings such as `parallelMode` or `diagnosticMessages`. 3. Commit any `global.json` the template created or updated, so every machine and CI agent picks the same test runner. 4. Delete `UnitTest1.cs` once the first real test exists. ## Avoiding the wrong template - In documentation and onboarding notes, write `dotnet new xunit3`, not `dotnet new xunit`, when v3 is intended. - When reviewing a new test project, check for `xunit.v3` or `xunit.v3.mtp-*` package ids and `OutputType Exe`; a plain `xunit` reference means the v2 template was used. - A project created from the SDK template can be upgraded with the same steps as any v2-to-v3 migration.

  • How can you tell from a project file which template created it?
    An SDK `xunit` project references `xunit`, `xunit.runner.visualstudio`, `Microsoft.NET.Test.Sdk` and `coverlet.collector`. An `xunit3` project has `<OutputType>Exe</OutputType>`, a global `Using` for `Xunit`, an `xunit.runner.json` item and a reference to `xunit.v3.mtp-v2`, or `xunit.v3.mtp-off` with the VSTest packages when created with `--test-runner vstest`.
  • What does the --command-line option of the xunit3 template change?
    It chooses the command-line experience of `dotnet run` for the test executable: `xunit` (default) gives xUnit.net's native options such as `-class` and `-explicit`, while `mtp` adds `UseMicrosoftTestingPlatformRunner` so the executable presents Microsoft.Testing.Platform's command line instead. Tests behave the same either way.

  • On the .NET 10 SDK, dotnet new xunit creates an xunit.v3 project.
  • The xunit3 template is built into the .NET SDK and needs no template pack.
  • The xunit3 template defaults to net10.0.
  • --test-runner vstest makes the xunit3 template produce an xUnit.net v2 project.
  • The SDK's xunit template references xunit.v3.mtp-v2 since .NET 10.

Assumes the xunit.v3.templates package for xunit.v3 4.x and the .NET 10 SDK, whose built-in xunit template still creates an xUnit.net v2 project.