Which dotnet new template creates an xunit.v3 test project, and why does the .NET SDK's own xunit template not do so?
answer
- the SDK template still targets v2
- template pack xunit.v3.templates
- short name xunit3
- --test-runner mtp-v2 or vstest
- --framework defaults to net8.0
basics
~10 sThe 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 sThe .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# 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 vstestgo deeper
Remember: dotnet new xunit is still v2; use the xunit3 template from xunit.v3.templates for a v3 project.
Explain what xunit3 generates and its options (framework, test runner, command line, Native AOT).
Catch v2 projects created by habit in review, and choose template options that match the CI's test platform.
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.