• Assembly Fixtures: These allow a fixture instance to be shared between all tests in multiple classes, rather than between tests in a single class as IClassFixture had allowed up until v2.

• Automatically serialization of test case objects in TheoryData classes. This means that this unbelievable clunk:

   public class TestCase_ValidProduct : IXunitSerializable
   {
      public required string TestCaseName { get; set; }
      public required CreateProductArgs NewProduct { get; set; }
  
      public void Deserialize(IXunitSerializationInfo info)
      {
          XUnitSerializationHelper.Deserialize(this, info);
      }
  
      public void Serialize(IXunitSerializationInfo info)
      {
          XUnitSerializationHelper.Serialize(this, info);
      }
   }
  

  reduces to:

  public class TestCase_ValidProduct : IXunitSerializable
  {
      public required string TestCaseName { get; set; }
      public required CreateProductArgs NewProduct { get; set; }
  }
  

The price of this upgrade was that Test Explorer in VS Code either couldn't discover tests, or would show them as "Skipped" and refuse to run them:

Exactly the same thing happens when I scaffold a new XUnit 3 project using dotnet new xunit3.

These problems seem to stem from the fact that xUnit v3 uses the new Microsoft Test Platform (MTP) which is a replacement for the older VS Test platform, but C# Dev Kit extension in VS Code - which is responsible for discovering tests in a C# test project and providing these to the Test Explorer window - does not work properly with MTP (yet!).

It is worth mentioning that both VS Test and the newer MTP are test execution platforms - they are agnostic to the test harness used in test projects and works with any test harness e.g. MS Test, xUnit and NUnit.

I fixed the issues by making the test projects use the older VS Test platform instead that C# Dev Kit does work with.

These are the steps that you can take to make an xUnit v3 project - whether upgraded from v2 or newly scaffolded - work in Test Explorer in VS Code:

• Delete <PackageReference> to xunit.v3.mtp-v2 or just comment it out in the .csproj of your test project:

  <!--<PackageReference Include="xunit.v3.mtp-v2" Version="3.2.2" />-->
  

• Then add the following references:

  dotnet add package xunit.v3.mtp-off
  dotnet add package Microsoft.NET.Test.Sdk
  dotnet add package xunit.runner.visualstudio
  

  xunit.v3.mtp-off is a version of xUnit v3 package that has MTP support disabled and is a replacement for xunit.v3.mtp-v2 that I deleted above.

  Microsoft.NET.Test.Sdk provides targets and properties for building .NET test projects, regardless of the test harness - xUnit, NUnit, MS Test etc. - that they use. It is required for integrating the project with the VS Test platform.

  xunit.runner.visualstudio is the xUnit-specific adapter for VS Test

Then reload the window (bring up the Command Palette using shortcut key Ctrl+Shift+P or F12, then type Reload Window and press Enter), and press Refresh Tests button in Test Explorer:

You should now be able to see and run your tests.

The slight caveat is that individual TheoryData tests cases in a [Theory] test do not appear as separate tests cases like they used in the Test Explorer with xUnit v2. But I am happy to sacrifice this granularity for being able to use the shiny new features in xUnit v3.

The slightly trickier part is to put checks in Program.cs to exclude any startup code that cannot run at build time. This is typically done because configuration key/value pairs are not available at that time. For example:

if (!isBuildTime)
{
    connString = builder.Configuration.GetConnectionString("AppDB") ?? 
    throw new InvalidOperationException("Connection string 'AppDB' is not configured.");

    builder.Services.AddDbContext<AppDbContext>(
        options =>
        {
            options.UseNpgsql(connString);
        }
    );
}

The question is how to deduce that the API has been launched at build time, i.e. isBuildTime should be true?

The official way of doing this is to check that the assembly that invoked the API is "GetDocument.Insider":

var isBuildTime = 
	Assembly.GetEntryAssembly()?.GetName().Name == "GetDocument.Insider";

GetDocument.Insider.dll is the command line tool that automatically runs during build of the API if the .csproj includes the following reference:

<PackageReference Include="Microsoft.Extensions.ApiDescription.Server"
	 Version="10.0.7">
      ...
</PackageReference>

This package is a shim. It only provides build targets and props and hooks into the build of the API to run the command-line tool dotnet-getdocument. This tool in turn runs the command line tool GetDocument.Insider that we check for.

This is a pretty convoluted sequence:

1. Microsoft.Extensions.ApiDescription.Server provides targets that run during build of the API.

2. One of those targets runs the command line tool dotnet-getdocument

3. That in turn runs the command line tool GetDocument.Insider

4. That in turn runs the API and fetches the /openapi/v1/json (or other configured endpoint) to get the OpenAPI document and saves it to disk.

Checking in Program.cs if the API was invoked by the assembly GetDocument.Insider.dll to determine if it is running during build bothers me. It is a hack, and an uncomfortable one, for two reasons.

First, the name of the tool could change. If the sequence above gets cleaned up or modified in the future, the assembly GetDocument.Insider might vanish. This means we would need to change the check we do to compute if the API is running at build time for OpenAPI document generation.

Second, there is a standard, time-worn way for checking in ASP.NET if Program.cs is running in a specific environment and executing code conditionally based on that: runtime environments.

We could define a custom environment name, say BuildTime, that sits alongside the predefined environments Production, Development and Staging, and check for it in Program.cs:

isBuildTime = builder.Environment.IsEnvironment("BuildTime")

This is the canonical solution to the problem of determining if the API was launched at build time. The environment name is not going to change either - unlike the assembly name used in the official solution - because this is a custom environment name that we have handpicked for our build.

Unfortunately, there is no official way of declaring the environment name under which the API should be launched during build. Nor would you have any success with setting the environment variables ASPNETCORE_ENVIRONMENT or DOTNET_ENVIRONMENT on the command line before building the API. In other words, this would not work:

export ASPNETCORE_ENVIRONMENT=BuildTime
dotnet build

The environment simply doesn't get picked up and passed to the API by the tooling that generates the OpenAPI document at build time.

However, I did succeed in setting the environment name so that it gets picked up by the API when it runs during build.

I show my solution in the next section. But my conclusion is that, even though it sounds like the right thing to do, actually doing it is even more fragile and hacky than the official solution.

So, until .NET provides an official way of providing a custom environment name to an API during build-time OpenAPI document generation - and there is an open issue in dotnet/aspnetcore repo requesting exactly this feature - I would just (grit my teeth and) use the official solution:

var isBuildTime = 
	Assembly.GetEntryAssembly()?.GetName().Name == "GetDocument.Insider";

if (!isBuildTime) { 
	// load services and middlewares that require 
	// configuration key values that are not available at build time
	
}

Providing a custom environment to an API for build-time for OpenAPI generation - DON'T DO THIS

I define a custom .NET environment named BuildTime in my minimal API project.

While you can pass command-line arguments to the dotnet-getdocument tool using property <OpenApiGenerateDocumentsOptions> in the API's csproj:

<OpenApiGenerateDocumentsOptions>--file-name openapi_v1</OpenApiGenerateDocumentsOptions>

none of these corresponds to the environment name of the API that would be launched.

Also, you cannot pass --environment Development command line argument for dotnet run (dotnet build does not have an --environment argument):

dotnet run --environment BuildTime

using the <OpenApiGenerateDocumentsOptions> csproj property.

Nor can you set ASPNETCORE_ENVIRONMENT or DOTNET_ENVIRONMENT environment variable to "BuildTime" in such a way that it would be available to the API that would be launched during build (as explained in the previous section).

So to get the GetDocument.Insider tool to launch the API in environment "BuildTime", you essentially have to first construct the command line for running the GetDocument.Insider yourself then execute the command with environment variable ASPNETCORE_ENVIRONMENT set to BuildTime. This is done like this:

1. add a reference to Microsoft.Extensions.ApiDescription.Server as before using dotnet add package Microsoft.Extensions.ApiDescription.Server which reflects in the csproj like this:

   <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.6">
     <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     <PrivateAssets>all</PrivateAssets>
   </PackageReference>
   

2. But DISABLE automatic OpenAPI document generation on build to via these properties in the csproj:

   <PropertyGroup>
       <OpenApiGenerateDocuments>false</OpenApiGenerateDocuments>     <OpenApiGenerateDocumentsOnBuild>false</OpenApiGenerateDocumentsOnBuild>   
   </PropertyGroup>
   

   Also REMOVE the following properties we added originally. They are not going to be used any more:

   <PropertyGroup>
   <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
   <OpenApiGenerateDocumentsOptions>--file-name openapi</OpenApiGenerateDocumentsOptions>
   

```

1. Construct the command line for running GetDocument.Insider tool yourself, then execute this command line, by putting these targets in your csproj:

   <Target Name="ResolveApiDescriptionPackage">
       <ItemGroup>
         <_ApiDescriptionPackage Include="@(PackageReference)" Condition="'%(Identity)' == 'Microsoft.Extensions.ApiDescription.Server'" />
       </ItemGroup>
     </Target>
   <Target Name="GenerateOpenApiDocumentsAfterBuild" DependsOnTargets="ResolveReferences;ResolveApiDescriptionPackage" AfterTargets="Build">
       <PropertyGroup>
         <_DetectedApiVersion>%(_ApiDescriptionPackage.Version)</_DetectedApiVersion>
         <_DotNetGetDocumentCommand>dotnet "\((NuGetPackageRoot)microsoft.extensions.apidescription.server/\)(_DetectedApiVersion)/tools/dotnet-getdocument.dll" --assembly "\((TargetPath)" --file-list "\)(MSBuildProjectDirectory)/obj/cloudcartapi.OpenApiFiles.cache" --framework "\((TargetFrameworkIdentifier),Version=\)(TargetFrameworkVersion)" --output "\((MSBuildProjectDirectory)" --project "\)(MSBuildProjectFullPath)" --assets-file "\((ProjectAssetsFile)" --platform "\)(Platform)" --file-name openapi_v1</_DotNetGetDocumentCommand>
       </PropertyGroup>
       <Exec Command="$(_DotNetGetDocumentCommand)" EnvironmentVariables="ASPNETCORE_ENVIRONMENT=BuildTime;DOTNET_ENVIRONMENT=BuildTime" LogStandardErrorAsError="true" />
     </Target>
   

2. Finally, for robustness, I add this flourish to the csproj:

   <!-- 
   The command run in GenerateOpenApiDocumentsAfterBuild target above is a little bit brittle and breaks if the major version of the ApiDescription package does not match the major version of .NET set in <TargetFramework> property a the top.
   
   While this is a very unlikely scenario, because the major version of every .NET package should be/would be the same as the major version of .NET framework that the project compiles against, still f the scenario does arise, instead of getting to the point where GenerateOpenApiDocumentsAfterBuild target runs and fails with an unedifying error, in this task we detect the situation early, show an informative error message and stop the build.
   -->
     <Target Name="ValidateApiDescriptionVersion" BeforeTargets="Build" DependsOnTargets="ResolveApiDescriptionPackage">
       <PropertyGroup>
         <_TFMajorVersion>\(([System.Text.RegularExpressions.Regex]::Match('\)(TargetFramework)', 'net(\d+)').Groups[1].Value)</_TFMajorVersion>
         <_ApiDescriptionVersion>@(_ApiDescriptionPackage->'%(Version)')</_ApiDescriptionVersion>
         <_ApiDescriptionMajorVersion>\(([System.Text.RegularExpressions.Regex]::Match('\)(_ApiDescriptionVersion)', '^(\d+)').Groups[1].Value)</_ApiDescriptionMajorVersion>
       </PropertyGroup>
       <Error Condition="'\((_TFMajorVersion)' != '\)(_ApiDescriptionMajorVersion)'" Text="Version mismatch: TargetFramework '\((TargetFramework)' has major version \)(_TFMajorVersion) but Microsoft.Extensions.ApiDescription.Server version '\((_ApiDescriptionVersion)' has major version \)(_ApiDescriptionMajorVersion). Update this package to a version whose major version number is same as that of the target framework (specified in TargetFramework property in this csproj file)." />
     </Target>
   

The real issue isn't that this solution is a bit messy, it is that it is even more fragile: if in a future version Microsoft change the name of the file dotnet-getdocument.dll or its location within the package microsoft.extensions.apidescription.server or names of any of the numerous arguments we are passing to it, this logic would break.

On the other hand, in the solution given in MS Docs (and excerpted from there in the article above):

var isBuildTime = Assembly.GetEntryAssembly()?.GetName().Name == "GetDocument.Insider";
    
if (!isBuildTime) { 
	// load services and middlewares that DO require configuration key values that are not available at build time
	
}

if the name of assembly changes we would know about it through the Release Notes of the .NET version in which this happens, the new official solution would again be documented/updated, and we can update our code.

Hence why the official, if fragile-looking, solution for conditionally excluding code in Program.cs that requires configuration data is the one that should be used.