Forem: Naveed Ausaf

OpenAPI in .NET 10: From Setup to Build-Time Generation (with Scalar UI)

Naveed Ausaf — Mon, 20 Apr 2026 18:30:27 +0000

Why OpenAPI and Build-Time Generation Matter

OpenAPI is the industry standard for describing REST APIs.

By providing machine-readable descriptions of your endpoints, OpenAPI enables a rich ecosystem of tools such as

Scalar UI, which turns the raw JSON of an OpenAPI document into beautiful, interactive documentation of your API where you can also test the API like you would with Postman or Hoppscotch.
Spectral, which lints an OpenAPI document for issues and inconsistencies.
Microsoft Kiota, which generates strongly typed client SDKs so you don't have to write manual HTTP wrapper code.

ASP.NET Core has excellent built-in support for auto-generating OpenAPI documents from your code, an approach known as Code-First (as opposed to Design-First, where you author the document by hand upfront).

In this post I will show you how to set up OpenAPI in your .NET APIs. This setup will include :

OpenAPI document generation
Scalar UI for interactive browsing of the OpenAPI spec and API testing
build-time generation so that the OpenAPI document is produced during every build

The last of these — build-time generation — matters more than it might seem, and I'll explain exactly why when we get to it.

Here's what Scalar UI looks like once it's set up:

Sample Code

You can see OpenAPI document generation in action in a .NET 10 minimal API in the sample code repo on GitHub.

To run the project, press F5 in VS Code or GitHub Codespace, or run dotnet run on the command line.

This would launch the Scalar UI shown above in which you would be able to browse the generated OpenAPI document and test the API.

Set up OpenAPI document generation and Scalar UI

In order to set up OpenAPI document generation and Scalar UI in your .NET minimal API project, proceed as follows:

Add a reference to package Microsoft.AspNetCore.OpenApi.
This package provides classes that enable automatic OpenAPI document generation.

Add statements builder.Services.AddOpenApi(); and app.MapOpenApi(); to Program.cs, as described here in MS Docs.
This enables the OpenAPI document for the API to be auto-generated and served at /openapi/v1.json.

var builder = WebApplication.CreateBuilder(args);

// adds and registers the OpenAPI document generator and related services in the DI container
builder.Services.AddOpenApi();

var app = builder.Build();

// exposes endpoint `/openapi/v1.json` over which the autogenerated OpenAPI document for the API is served
app.MapOpenApi();

app.Run();

Modify Handlers: Several extension methods provided by the package Microsoft.AspNetCore.OpenApi can be chained to route prefix and handler registrations to provide OpenAPI metadata about them.

These augment the metadata that OpenAPI services automatically deduce from handler signatures (parameter lists, return types etc.).

I gather together endpoint handlers for all operations at a given route segment, such as /product, in a static Handlers class (ProductHandlers in the snippet below; see sample code for the full implementation).

In this class I also expose a static MapRoutesAndDescribe method that both registers those handlers and chains OpenAPI extension methods like .WithTags(), .WithSummary() and others to declare OpenAPI metadata on both the individual handlers and on the route prefix (/products below):
```
internal static RouteGroupBuilder MapRoutesAndDescribe(RouteGroupBuilder baseRouteGroup)
    {
        // OpenAPI Tag "Product Operations" is added to the group of handlers in this Handlers class under Route prefix `/products`
        var routeBuilder = baseRouteGroup.MapGroup(RoutePrefix).WithTags("Product Operations");

        routeBuilder.MapPost("/", HandleCreateProduct).WithName(HandlerNames.CreateProduct).WithSummary("Creates a new product in the system.");

        routeBuilder.MapGet("/{id}", HandleGetProduct).WithName(HandlerNames.GetProduct).WithSummary("Fetches the product details for a given product id.");

        return routeBuilder;

    }
```
Whether you use Handlers classes like the one given above to register groups of handlers in your API, or register them in some other way, chain .WithTags(), .WithSummary() and other extension methods given here to add metadata to individual handler registrations.

If you create a RouteGroupBuilder for the route segment for a group of handlers (as the Handlers class above does), then chain a WithTags() to this also, as I have done above.

When viewed in Scalar UI (which we'll set up shortly), the result should look something like the screenshot below. In this, I have highlighted the bits that correspond to the metadata declared in snippet above in red outline:
Add XML documentation comments on handlers and on the types of parameters that are bound to HTTP request. For example, on the handler:
```
/// <summary>
/// Creates a new product in the database.
/// </summary>
/// <param name="p">Details of the product to be created.</param>
/// <response code="201">Product created successfully. URL to GET the newly created product is in the <c>Location</c> response header.</response>
internal static async Task<Created> HandleCreateProduct(CreateProductArgs p, IProductService productService, LinkGenerator linkGen)
{
```
And since CreateProductArgs p, being the only complex-type parameter in the handler's parameter list, is automatically bound to the JSON body of the HTTP request, we need to provide XML documentation comments for it too:
```
/// <summary>
/// Details of the product to be created
/// </summary>
public record CreateProductArgs
{

    /// <summary>
    /// Name of the product
    /// </summary>
    public required string Name { get; set; }

    /// <summary>
    /// A description for the product
    /// </summary>
    public required string Description { get; set; }

    /// <summary>
    /// URL of an image of the product
    /// </summary>
    public string? ImageUrl { get; set; }

    /// <summary>
    /// Price of the product. Must be greater than or equal to zero.
    /// </summary>
    public required decimal Price { get; set; }
}
```
The XML documentation comments given above generate OpenAPI documentation for the endpoint handler that looks like this:

At this step, please ensure the following:
- Only provide <param> tags for those parameters that are bound to request parameters. For example CreateProductArgs p above, being the only complex type parameter in the handler's parameter list, is automatically bound to JSON request body in a minimal API. So I have included a <param> tag for it. On the other hand, IProductService productService and LinkGenerator linkGen are not bound to contents of the HTTP request (both of these happen to be sourced from DI container). Therefore I have made sure that there is no <param> tag for either of them. Why do this? because if we include a <param> tag in XML documentation comments for a parameter that is not model-bound (i.e. not bound to any part of the HTTP request) then its documentation shows up spuriously as part of the request for the endpoint in generated OpenAPI spec. Screenshot below shows this happening if I include a <param> tag for LinkGenerator linkGen parameter in the above handler which is resolved from DI container:

* **Handler methods should NOT be `private`**. XML documentation comments of `private` handlers are not visible to OpenAPI document generator. This is why I made them `internal` in the code shown above.

Configure .csproj to collect the XML documentation comments in your project and compile them into file bin/<build configuration e.g. Debug>/net10.0/<project name>.xml.
When this file is present, it will be automatically used in generating OpenAPI document.
To configure generation of the XML documentation comments file at build time, place <GenerateDocumentationFile>true</GenerateDocumentationFile> in your API project's .csproj file within a <PropertyGroup> element, e.g. :
```
<PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
```
When you build your API project (e.g. with dotnet build), because of including the above attribute in .csproj, you would get warnings:

These warnings would be of one or both of the following two types:
- CS1591 warns you that XML documentation comments are missing altogether on a type or member that is publicly visible.
- CS1573 is reported when an XML documentation comment - a <param> tag - is specified for some but not all parameters on a method. This warning would definitely be reported if you follow the convention described above of always having a <param> XML documentation tag for every parameter in a handler method that is model-bound (i.e. binds to some part of the incoming HTTP request) and always omitting it for every other parameter in the handler.
I personally like to turn both of these off, because:
- CS1573 arises by design. I might as well get rid of the noise by silencing these
- In API project, I do not always have XML documentation comments on every public type or member. I only provide these where they would go into the generated OpenAPI document. Therefore like to turn off CS1591 also.
If you would like to turn these warnings off, add a <NoWarn> XML element within the same <PropertyGroup> in which you added the <GenerateDocumentationFile>true</GenerateDocumentationFile> MS Build property above:
```
 <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    
    <GenerateDocumentationFile>true</GenerateDocumentationFile>

    
    <NoWarn>$(NoWarn);1591;1573</NoWarn>
  </PropertyGroup>
```
Add Scalar UI: Add a reference to package Scalar.AspNetCore and add line app.MapScalarApiReference(); to Program.cs (as described here).
You can place it right after the app.MapOpenApi(); call you add to Program.cs above.

Adding this line is what would serve the Scalar UI to browse the raw JSON of the OpenAPI document in an interactive web app (the Scalar UI) where you can also test your API.

If you have completed the steps above, you can now run the API and navigate to http://localhost:xxxx/scalar to browse the API's OpenAPI documentation and test it (as shown in the screenshot in intro section above).

You can also see the raw JSON OpenAPI document at http://localhost:xxxx/openapi/v1.json.

Note: Other ways of adding OpenAPI metadata to your project

In addition to these ways of adding OpenAPI metadata that you exercised above:

extension methods to provide metadata on handler and RouteGroupBuilder registrations
Starting in .NET 10, XML documentation comments on the handlers and on the types used on those handlers can also be picked up by OpenAPI document generator. This is more powerful now than in the previous incarnation of this facility that existed before .NET 7.

you can use the following to tweak OpenAPI metadata in your API project:

C# attributes provided by the same package (Microsoft.AspNetCore.OpenApi)
If other techniques - extension methods, C# attributes and XML documentation comments - fall short, OpenAPI document generation can be customized using custom transformers provided to builder.Services.AddOpenApi() call in Program.cs.

Set up Build-time Generation of OpenAPI JSON document

The Problem with Runtime-Only Generation

The reason the OpenAPI document is only generated at runtime is that the services need to examine OpenAPI metadata explicitly configured in code in addition to other reflection-based sources. However, relying solely on runtime generation creates a gap in the development lifecycle. The document is missing at build time, where it is needed for:

Linting: Automatically checking the document for issues such as errors and OWASP compliance using a tool like Spectral.
Review of Changes to the Contract: Inclusion in your Git commit so that any changes to it are visible during the Pull Request (PR) review of the commit.

The second point is vital. Because the document is synthesized from numerous sources of metadata — XML documentation comments, C# attributes, extension method calls and custom configuration code — that are dispersed all over the API code, a small change to one file can quietly alter the OpenAPI document.

But this document is your API contract: any change to it should be reviewed before the corresponding code reaches production.

A natural place to do this review is as part of the PR review for the commit that led to those changes. However, this is only possible if the OpenAPI document (e.g. openapi.json) is generated during a pre-commit build (e.g. to run tests), then checked into source control along with the code changes.

In the section below, I show you how to set up build-time generation for your API's OpenAPI document, so that it is generated whenever the API project is built and subsequently checked into source control along with the code changes.

Set up Build-time Generation

Set up build time generation of OpenAPI document so it can be checked in to source control:

In the project folder on the terminal, run:
```
dotnet add package Microsoft.Extensions.ApiDescription.Server
```
This package contributes build assets to the .csproj that execute during build of the project. They run the API during the build process, call the /openapi/v1.json endpoint to fetch the dynamically generated OpenAPI document and save it as bin/<configuration such as Debug>/netX.0/<Project Name>.json.

Clearly the path doesn't work if we are going to check it into source control (bin folder is rightly excluded from source control in .NET .gitignore files). We will fix this in the next step.
Modify the output path and filename: To put the generated OpenAPI document into project root, place the following in your .csproj file.
You have to pass --file-name in the XML tag <OpenApiGenerateDocumentsOptions></OpenApiGenerateDocumentsOptions> in order to change the path. Therefore it is an opportunity to change the name of the document from <ProjectName>.json to something else. I have changed it to openapi.json below which I prefer to the default as it is more stable (does not depend on project name).
```
<PropertyGroup>
<OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
<OpenApiGenerateDocumentsOptions>--file-name openapi</OpenApiGenerateDocumentsOptions>
</PropertyGroup>
```

Modify Program.cs: The API is executed during build when configuration information such as database connection strings and API keys would likely not be available (especially in CI/CD pipeline where build is cleanly separated from the execution/deployment jobs in which configuration information is sourced securely).

Therefore we want to modify Program.cs so that if it is executed during build - by the OpenAPI document generation step in the build - then services and middlewares that require configuration information are not added.

Note: the sample code repo does not include this modification to Program.cs. However, I regularly use the following technique - from here in MS Docs - to exclude .AddXXX() statements to add those services and .UseXXX statements to add those middlewares that require configuration information to be available.

To understand the condition in the conditional execution (if) blocks, note that the .NET assembly for command line tool that launches the API during build to fetch the OpenAPI document has assembly name GetDocument.Insider. Therefore we check for the fact that the API project has been launched from this assembly to deduce that this run is happening at build time.

// Program.cs file

// We check the entry assembly name to detect if the app is being executed by the OpenAPI build tool (whose assembly is named "GetDocument.Insider") 
// See MS Docs: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-10.0&tabs=net-cli%2Cnetcore-cli#customize-runtime-behavior-during-build-time-document-generation
var isBuildTime = Assembly.GetEntryAssembly()?.GetName().Name == "GetDocument.Insider";

if (!isBuildTime) { 
    // exclude OpenTelemetry initialization as connection information for telemetry backend is not going to be available at build time when the app is run to generate Open API document
    builder.AddOpenTelemetry(); 
}

// other statements for adding services to DI container...

if (!isBuildTime) { 
    //exclude adding app's DbContext to DI container as database connection string is not going to be available at build time when the app is run to generate Open API document
    connString = builder.Configuration.GetConnectionString("CloudCartDB") ?? throw new InvalidOperationException("Connection string 'CloudCartDB' is not configured.");

    builder.Services.AddDbContext<CloudCartDbContext>(
        options =>
        {
            options.UseNpgsql(connString);
            if (builder.Environment.IsDevelopment())
            {
                options.EnableSensitiveDataLogging();
            }

        }
    );
}

var app = builder.Build();

// add middlewares and endpoints...

app.Run();

If you have completed the above steps, then whenever your project is built, the OpenAPI document - openapi.json in the API project folder - would be regenerated.

Other things you can do with your OpenAPI document

Now that you have set up OpenAPI document generation in your API, here are some pointers to other things you can do with the document:

Lint it with Spectral: Spectral is an amazing tool for linting OpenAPI documents for a host of issues such as correctness, compliance with your organizational best practices and any OWASP issues in API design that may be detectable from its OpenAPI document.
I have not set up Spectral in the sample code as it is a Node.js tool and its setup would rather detract from the .NET focus of this article.
However, if you are interested in setting it up, here are some links:
- See this post for setting up Spectral. The instructions should work fine run from the solution root - some NPM and Node.js files will get created in that folder beside the sln/slnx file but it should not interfere with the .NET solution. I haven't tested this specific configuration myself as my own spectral setups have been in polyglot solutions containing .NET APIs where I have installed Spectral one level above the .NET solution folder.
- Build project and run Spectral on it at every Git commit - so that the commit is aborted if linting fails - using Husky.NET.
- Check out Spectral's own documentation.
Return Problem Details responses and include them in your OpenAPI document: IETF Problem Details RFC 9457 is a superb, really lightweight standard for returning problems and errors from your APIs. It also has pretty good support in .NET Core.

I have an upcoming dev.to post on how to return Problem Details responses from a .NET Core minimal API and include these in the OpenAPI document. If you follow me, you would get notified.

Conclusion

OpenAPI document generation in a .NET minimal API is a matter of assembling the right pieces — the Microsoft.AspNetCore.OpenApi package, a handful of extension methods and XML documentation comments, Scalar UI for interactive browsing and testing, and build-time document generation.

The last of these items is particularly important: once you set up your OpenAPI document to be produced at build time, it can be committed alongside your code, contract changes become visible in PR diffs and linting can run automatically — your API's public contract is transparent throughout the DevOps pipeline and no longer something that only materializes at runtime.

Patterns for Routing in ASP.NET Minimal APIs

Naveed Ausaf — Mon, 20 Apr 2026 08:10:06 +0000

In ASP.NET Core, Routing is the mechanism that connects an incoming HTTP request to the code responsible for handling it. It performs two basic functions:

Routing: maps URLs in incoming HTTP requests to endpoint handlers that would handle those requests.
Link Generation: given a handler, generate a URL (that may be used to invoke that handler in the future). This, in a sense is the opposite of Routing.

Minimal APIs are great because they get rid of the boilerplate and give you a great deal of flexibility in how to construct your API. This flexibility is also their downside and needs to be harnessed with clear patterns for organising code.

This post gives a few patterns for Routing that would help to keep the code of your ASP.NET Minimal API projects well-organised.

You can skip the intro to routing and go straight to the patterns

How Routing Works in ASP.NET

To understand routing, we have to look at two distinct phases in an ASP.NET application: Startup and Runtime.

1. The Startup Phase: Registration

During application startup (usually in Program.cs), you register your endpoints, mapping a route template (like /products/{id}) to a handler (a delegate or method).

var app = builder.Build();

// set up middleware pipeline with `app.UseXXX` calls

// register endpoint handlers with `app.MapXXX` calls
app.MapGet("/products/{id}", (int productId) => {
  // find and return product with given `productId`
}).WithName("get-product");

app.MapPost("/products", (CreateProductArgs product) => {
  // create product in database with details given in `product`
}).WithName("create-product");

// start the app
app.Run();

Optionally, you can also register middlewares using app.UseXXX() methods - these intercept your request and potentially process, or alter it, until it reaches a handler.

Registering endpoint handlers like this makes Program.cs large and messy. Controlling this "bloat" is what most of the patterns in this post are about.

2. The Runtime Phase: The Middleware Pipeline

When a request hits your server, it travels through the Middleware Pipeline.

The two key middlewares involved in routing are the Routing Middleware and the Endpoint Middleware:

RoutingMiddleware: When a request comes in, this middleware matches the URL to a registered route template. It doesn't execute the code yet; it simply selects the "Endpoint" - the handler registered for the matched route template - and attaches it to the HttpContext.
If you don't call app.UseRouting() in Program.cs, this would be added automatically as the first middleware in the pipeline when you call app.Run().
The "In-Between": Any middleware placed between these two, like authorization and authentication middlewares, can now see which handler is about to be called and make decisions based on that, including returning a response that short-circuits the rest of the pipeline.
EndpointMiddleware: This is the final stop. It takes the handler stored in the HttpContext, performs Model Binding - mapping request contents such as URL parameters like {id} and request body JSON data to handler method's arguments - and executes the handler.
This is the last middleware in the pipeline and added automatically if you didn't call app.UseEndpoints().

The response then travels back through the middleware pipeline in reverse order.

For more details, see the MS Docs on Routing.

Sample Code

Patterns 1 - 3 are illustrated in a .NET minimal API project in the sample code repo on GitHub.

Pattern 4 is not part of the sample code but is quite straightforward.

Pattern 1: Handlers class

The Pattern: Move your route registrations and handlers out of Program.cs and into dedicated service-specific static classes each of which contains the endpoint handlers for a service or group and provides a public MapRoutes method to register them with ASP.NET.

Implementation

In a REST API a group would consist of all handlers that map to the same route such as /products and provide operations for the resource at that route, e.g. Products, but at different HTTP verbs (POST, GET etc.) and/or at different route segments (such as /products/{id} or /products).

We would move all handlers for /product out of Program.cs and into a Handlers class like this:

public class ProductHandlers
{
    public static class HandlerNames
    {
        public const string GetProduct = "get-product";
        public const string CreateProduct = "create-product";

    }

    public const string RoutePrefix = "/products";

    internal static RouteGroupBuilder MapRoutes(RouteGroupBuilder baseRouteGroup)
    {
        var routeBuilder = baseRouteGroup.MapGroup(RoutePrefix);

        routeBuilder.MapPost("/", HandleCreateProduct).WithName(HandlerNames.CreateProduct);

        routeBuilder.MapGet("/{id}", HandleGetProduct).WithName(HandlerNames.GetProduct);

        return routeBuilder;

    }

    internal static async Task<IResult> HandleGetProduct(int id, IProductService productService) { 
        /* handler logic */ 
    }

    internal static async Task<IResult> HandleCreateProduct(CreateProductArgs product, IProductService productService, LinkGenerator linkGen) {
        /* handler logic */
    }

}

Then in Program.cs, create a RouteGroupBuilder for the base URL of the API, then call the static MapRoutes method in the Handlers class to register all the handlers contained in the class:

// In Program.cs
var app = builder.Build();

RouteGroupBuilder v1ApiRouteGroup = app.MapGroup("/v1");

ProductHandlers.MapRoutes(v1ApiRouteGroup);

This is what the Handlers class contains:

A HandleXXX method for each endpoint handler

A nested static class HandlerNames
This contains string constants for handler names that are provided to .WithName call that is chained to a .MapXXX call for handler registration.

public static class HandlerNames
{
    public const string GetProduct = "get-product";
    public const string CreateProduct = "create-product";

}

Constant RoutePrefix. This is the common prefix of URLs of handlers in the group:
```
public const string RoutePrefix = "/products";
```
Being public allows it to be used in unit- and integration tests.
A MapRoutes static method that does the following:
- takes a RouteGroupBuilder baseRouteGroup argument that represents the base URL of the API - e.g. / or, if your API versioning is based on base URL prefixes for major version numbers, then something like /v1 as used above
- Registers all handlers in the class at RoutePrefix relative to the baseRouteGroup
- Declares a name for each handler that is unique among all handlers registered in the API app
In the example above, MapRoutes registers two handler methods, HandleCreateProduct and HandleGetProduct at routes /v1/products and /v1/products/{id}, with respective names create-product and get-product that are unique among all handlers registered in the API application.

Benefits

Clean Program.cs: As your app grows, Program.cs can quickly become a 1,000-line "god file." This keeps it focused on high-level configuration by moving both the handlers themselves and the code for their registration out of it.
Cohesion: All handlers for a service or a REST are now to be found in the one place together with their registration details (including their names and the routes at which they map).
Open API metadata: MapRoutes in the Handlers class is the perfect place to chain .WithTags(), .WithSummary() and other extension methods to provide Open API metadata on RouteGroupBuilder for the route prefix for the whole group of handlers and on handler registrations themselves.
see example of this in the sample repo.
The Clean Architecture Advantage: If your API follows Clean Architecture, in particular if you separate:
- protocol specific Interface Adapters such as the two HTTP/REST endpoint handlers above
- from the business logic of the operations which the code above hints is contained in the injected IProductService implementation.
then your endpoints handlers would only be thin HTTP/REST wrappers over the more substantial operation logic contained in the actual business logic classes. They only handle concerns like:
- identifying routes at which requests are to be received (a REST concern)
- returning appropriate HTTP codes such as 2xx in case of success and 4xx or 5xx in case of errors (an HTTP concern)
- sending back data in a format that API callers can understand e.g. JSON (arguably a REST concern)
- in case of errors, translating exceptions thrown by business logic services into IETF Problem Details responses to send back to the API caller (arguably a REST concern)
- describing themselves for OpenAPI spec generation (see the section below).
In this case it may make more sense for you to collect all of the endpoint handlers for a particular functionality or REST resource - such as all the handlers that invoke business logic that pertains to Products or Customers - in a single class (e.g. called ProductHandlers or CustomerHandlers), rather than have a separate file for each endpoint handler as per the REPR pattern.

Of course if your endpoint handlers get too big or too numerous, you can still move them out into individual files as per the REPR pattern.

Pattern 2: Name Handlers for Reverse Routing

The Pattern: Never hardcode URLs when returning "Created" or "Redirect" results. Instead, use the LinkGenerator to resolve URLs by the handler's name.

Implementation

private static async Task<Created> HandleCreateProduct(CreateProductArgs product, IProductService productService, LinkGenerator linkGen)
{
    var id = await productService.Create(product);
    // Path-based generation is safer than URI-based
    // HandlerNames.GetProduct const has value "get-product"
    var path = linkGen.GetPathByName(HandlerNames.GetProduct, new { id });
    return TypedResults.Created(path);
}

Suppose the id of the created product is 6f0ce3bd-cd86-425d-801a-d2c3e313cecf, then the returned URL would be:

/products/6f0ce3bd-cd86-425d-801a-d2c3e313cecf

You can see in MapRoutes above how this handler is registered (in the usual way).

The key here is the LinkGenerator that is resolved from DI container by the model binder that is invoked by the EndpointMiddleware and injected into the handler.

Its GetPathByName method computes a URL to the handler with unique name get-product, with first route parameter ({id}, see handler registration for get-product handler in MapRoutes above) set to the id of the newly created Product returned by IProductService.Create.

Benefits

Refactor-Friendliness: If you change your route template from /product/{id} to /catalog/{id}, you don’t have to hunt through your code to update string URLs.
Decoupling: Handlers don't need to know the structure of the rest of the app's URL space.
Security: By using GetPathByName instead of GetUriByName, you prevent Host Header attacks. GetPath returns a relative path (e.g., /product/12), whereas GetUri includes the domain, which can be manipulated if your server isn't strictly configured to filter host headers.
In fact, not relying on the Host header value anywhere in your application code - the base URL at which the client originally sent the request - is one of the easiest ways of preventing Host Header attacks.
This is also the reason why I do not use TypedResults.CreatedAtRoute() convenience method which does the same thing as TypedResults.Created() but does not required you to first have LinkGenerator injected and call some GetPathXXX() method on it yourself; it uses the LinkGenerator behind the scenes so you don't have to. The problem is it returns an absolute URI e.g. https://www.example.com/v1/products/6f0ce3bd-cd86-425d-801a-d2c3e313cecf rather than the root-relative URI that the method shown above returns which is safer.

Pattern 3: Routing without Validation

The Pattern: Keep route constraints (e.g., {id:int}) to a minimum and avoid using them for business logic validation.

Benefits

Route constraints are for discovering the correct endpoint. If a constraint fails, ASP.NET Core returns a 404 Not Found instead of running your handler.

However, if the ID exists but is simply invalid (e.g., a negative number), you still want your endpoint handler to run when it could send back a helpful 400 Bad Request or 422 Unprocessable Content response with a descriptive message or JSON to describe the error in more detail.

Better yet, validate the request with a library such as Fluent Validation or .NET's built-in validation facilities (made automatic in .NET 10 minimal APIs) return the validation error in IETF Problem Details format. I have an upcoming post on the topic. If you follow me, you would get notified!

Pattern 4: Prefer the "Double Star" Catch-all

The Pattern: When capturing a file path or a multi-segment URL, use the ** prefix (e.g., /{**slug}).

Benefits

While both * and ** capture the remainder of a URL in a route template, they handle "Reverse Routing" differently.

A single * will URL-encode forward slashes (turning / into %2F).
A double ** keeps the slashes as they are. If you are generating a link to a file path, you almost certainly want the latter.

Conclusion

Routing in Minimal APIs is deceptively simple, but by moving logic out of Program.cs and leaning on LinkGenerator, you create an API that is both easier to maintain and more secure by default.

Use .env files for .NET local development configuration with VS Code

Naveed Ausaf — Mon, 14 Jul 2025 21:33:51 +0000

The Problem with .NET Development Configuration

Most ecosystems I use - Node.js, Docker/Compose, Terraform - expect configuration to come from environment variables.

In production, and other non-local environments, the hosting service loads data from configuration stores (e.g. Azure App Configuration and AWS AppConfig) and secret managers (like Azure Key Vault and AWS Secrets Manager) and sets these as environment variables before launching code.

For local development, config lives in .env files and is loaded automatically into environment variables by the framework or the launcher. Such .env files also typically contain secrets; this is mitigated by excluding them from the repo in .gitignore.

Either way - and in any environment - the app code only ever looks for its configuration in environment variables, which is in keeping with the philosophy of 12-factor apps.

Except in .NET!

In .NET, production configuration would still get loaded from environment variables that are injected by the hosting platform (e.g. from Azure App Configuration references or Key Vault references).

However, in local development, a .NET project loads configuration from an assortment of sources. This makes local .NET config stick out like a sore thumb when working in polyglot workspaces, where everything else just uses .env files.

For example, in a workspace in which I have a .NET Minimal API alongside a Next.js frontend and a Docker Compose compose.yaml, both Next.js and Docker Compose can take in config data in .env files. Here, I would like to use an .env file such as the following to configure the .NET API also:

ASPNETCORE_ENVIRONMENT=Development
ASPNETCORE_URLS=http://localhost:3022
ALLOWED_CORS_ORIGINS=http://localhost:3020
ConnectionStrings__EShop=<redacted>

Yet, instead of an .env file, we have the following sources:

appSettings.*.json configuration files. There are usually several of these, generated as part of boilerplate code.
.NET User Secrets Manager for secrets. This tool has its own quirks!

To complicate matters further, .NET projects also contain a scaffolded Properties/launchSettings.json. While originally meant for use in Visual Studio (the older product that predates VS Code), it still gets loaded and used when you launch your app through a Debug/Launch configuration in VS Code or on the command line using dotnet run. This too can provide config key/value pairs, sometimes without you realising it.

All these sources of development-time configuration obscure the effective source of a config value (there is a precedence order among the sources).

They are also discordant with how everything else is configured: via a single .env file.

For these reasons, I configure .NET projects in my polyglot workspaces to use .env files for local development, rather than the default sources above.

In this post, I'll show you how.

Note:

The solution given is primarily for VS Code. You may be able to adapt it for other IDEs such as JetBrains Rider or Visual Studio but those are outside the scope of this post.
To use a .env file with a .NET project, an alternative approach is to use dotenv-net. I explain at the end of this post why I don't like using it.

Step 1: Create `.env` files for VS Code launch configurations

Store all configuration, secret and non-secret, for a .NET project in a VS Code launch configuration in an .env file. I keep this next to launch.json in the .vscode folder:

I provide the path of such an .env file in envFile attribute in the launch configuration. For example, consider the compound launch configuration in launch.json given below. Note the envFile attributes:

{
  "version": "0.2.0",
  "compounds": [
    {
      "name": "Frontend/Backend",
      "configurations": [
        "Next.js: debug in full stack",
        ".NET: debug in full stack"
      ],
      "stopAll": true
    }
  ],
  "configurations": [
    {
      "name": ".NET: debug in full stack",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build-backend",
      "program": "${workspaceFolder}/flowmazonbackend/flowmazonapi/bin/Debug/net9.0/flowmazonapi.dll",
      "cwd": "${workspaceFolder}/flowmazonbackend/flowmazonapi",
      "stopAtEntry": false,
      "envFile": "${workspaceFolder}/.vscode/flowmazonapi.env",
      "sourceFileMap": {
        "/Views": "${workspaceFolder}/Views"
      },
      "requireExactSource": false
    },
    {
      "name": "Next.js: debug in full stack",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}/flowmazonfrontend",
      "program": "${workspaceFolder}/flowmazonfrontend/node_modules/next/dist/bin/next",
      "args": ["dev", "--port", "3020"],
      "console": "integratedTerminal",
      "envFile": "${workspaceFolder}/.vscode/flowmazonfrontend.env",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome",
        "webRoot": "${workspaceFolder}/flowmazonfrontend"
      }
    }
  ]
}

flowmazonapi.env configures the .NET minimal API and looks like this:

Logging__LogLevel__Default=Information
Logging__LogLevel__Microsoft.AspNetCore=Warning
ASPNETCORE_ENVIRONMENT=Development
ASPNETCORE_URLS=http://localhost:3022
ALLOWED_CORS_ORIGINS=http://localhost:3020
ConnectionStrings__FlowmazonDB=<redacted>
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-eu-west-2.grafana.net/otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=vscode_launch
OTEL_EXPORTER_OTLP_HEADERS=<redacted>

VS Code takes all the key value pairs in the specified .env file and sets them as environment variables. In ASP.NET Core, these are read by the environment variable config source in the Generic Host. This is the last and therefore the highest priority config source in ASP.NET Core host's default sequence, so it overrides any other source providing the same keys.

So having an .env file to configure a .NET project in a VS Code launch configuration means it replaces, for local development, the canonical combination of appSettings.*.json files and .NET User Secrets Manager. For example, the ConnectionStrings__FlowmazonDB=<redacted> line in the .env file shown above equates to the following in appSettings.json:

{
  "ConnectionStrings": {
    "FlowmazonDB": "<connection string redacted>"
  }
}

and these two lines in the .env file above:

Logging__LogLevel__Default=Information
Logging__LogLevel__Microsoft.AspNetCore=Warning

emulate the default log levels in the boilerplate appSettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

This means that once you have created a .env file like above, you can delete any appSettings* files in the project's folder, which we will do shortly.

SECURITY NOTE: Please make sure that you have a .gitignore file in the workspace root and that it contains the following line:

*.env

This would stop .env files, which may contain secrets such as connection strings for databases you use for local development, from getting checked in. Note that this, together with any secret scanning you might have in your online repo (such as GitHub Secret Scanning), guards against your local development secrets from leaking into your repo. It is important to be aware that, as with .NET User Secrets Manager, any secrets are still stored locally in plaintext.

All of your local development-time secrets and other configuration - for all projects and not just .NET if you have multiple ecosystems - are now in the .env files located in a single folder: in .vscode.

Moreover, all these colocated .env files are explicitly referenced in a single place: in launch configurations in launch.json in the .vscode folder.

If you have multiple launch configurations that need to be configured differently, you can define separate .env files for each of them.

Step 2: Provide an `.env` file to `dotnet` CLI commands

Even when you have one or more VS Code launch configuration to run a .NET project, you would likely still need to run commands on the project in its on the command line, e.g. to generate or apply EF Core migrations from the DbContext in an API project, or just to build run dotnet build on the .NET project or solution to check that it builds.

My solution for that is to use direnv to load the .env file for the API from .vscode folder, as environment variables specifically when you are in the .NET project's folder on the command line. Therefore when I run any dotnet commands in this folder, those environment variables are available as config key/value pairs for the project.

You can set up direnv for this purpose like this:

Install direnv using your operating system's package manager using the installation instructions given here.
On Windows you can do this by installing WinGet if you don't have it already. Then open a shell with Admininistrator permissions, one way of doing which is to find PowerShell, then right click it to select Run as administrator:

Then run command winget install direnv in this shell.
Hook direnv into your shell, as described here.
To do this for Bash on Windows, I did this by adding line eval "$(direnv hook bash)" at the end of the file ~/.bashrc where ~ is my user profile folder C:\Users\<my windows login name>.
Create a file named .envrc in the .NET project's folder with the following content:
```
dotenv <relative path to folder containing env file>/<env file name>.env
```
Normally you would have statements like export MY_VAR=<value> in a .envrc file to create environment variables. However, in this instance, the dotenv command in the .envrc file above is telling direnv to go and load the contents of the specified .env file as environment variables.
On the shell in your project's folder, run:
```
direnv allow
```
In general, an .envrc file for direnv should not be checked in. This is because it can directly contain environment variables and their values, some of which may be secrets. Even though this is not the case with the .envrc above, as a matter of good practice, I would add the following line to the .gitignore file in workspace root:
```
.envrc
```

Now whenever you cd into your .NET project folder in your shell, direnv would run automatically, run the .envrc file in the folder, and load your .env file as environment variables.

This means that while you are in that folder (or a subfolder within it) in your shell, you can run commands like dotnet run or dotnet ef migrations add or dotnet ef database update which require these configuration settings to run.

Also, when you move out of the folder (e.g. cd ..) or close your terminal instance, the environment variables get unloaded by direnv.

Additional Tips

The *.env.template files shown in the screenshot above are pre-filled versions of the respective .env files with secrets redacted (much like the snippets shown above). I do check these in and, together with setup instructions in the project's wiki, they make it easy to recreate the configuration. The *.env files on the other hand obviously DO NOT get checked in.
If you want to use this technique, please make sure to delete the <UserSecretsId>a-guid-here</UserSecretsId> element that would be present in your csproj if you have previously used .NET User Secrets Manager with the project. While .env would be the highest-precedence source anyway, deleting <UserSecretsId> would avoid surprises down the line such as when you realise that you had forgotten to set certain secrets in .env and they had been coming from User Secret Manager all along.
By the same token, it is worth deleting appSettings.json and any other appSettings.*.json files (such as appSettings.Development.json) in the .NET project folder (BUT make sure you have backed them up somewhere before deleting them).

Why I don't use `dotenv-net`

dotenv-net Nuget package can be used to load .env files into environment variables in code. For example:

using dotenv.net;

DotEnv.Load();

//then rest of Program.cs
var builder = WebApplication.CreateBuilder(args);
//...

DotEnv.Load() loads contents of .env file present in the directory of the running process as environment variables (you can also provide an alternate path as argument).

Next, when WebApplicaton.CreateBuilder(args) is called, the .NET configuration system loads config data from the default (or other configured) sources. This is when environment variables configuration provider loads as configuration the environment variables created by DotEnv.Load() earlier.

You can also wrap DotEnv into a configuration provider as this post shows.

The problem with this approach is essentially the mechanics: in ecosystems that are mainly configured using environment variables, .env files in local development are loaded by the launchers/orchestrators:

When Docker Compose launches apps/services for local testing, it reads key/value pairs from a .env file, then sets it as environment variables for every Docker container it launches. This is how your .NET app's container would receive its configuration.
When VS Code launches processes in a launch configuration - e.g. a .NET minimal API and a Next.js frontend - you can specify a separate .env file for each process. Thus each launch configuration can have its own set of .env files.
When the app is launched in a non-local environment, the host - Azure App Service, Kubernetes, ECS etc. - load configuration data from a configuration store and set it as environment variables before launching the process.

This way the processes launched for debugging or testing locally are completely oblivious to the source of configuration data and who loads/provides it. They don't know and don't care:

which .env files were used
whether .env files or some other configuration store (e.g. in Production) was used to retrieve configuration data
who loaded the config data

They just get the right set of environment variables to read at run time.

This makes processes really easy to configure, hence the popularity of this aspect of the 12-factor approach.

Hardcoding sources of configuration such as specific files - whether appsettings.*.json or .env - adds unnecessary complexity in my view.

It also again adds an exception for .NET behaviour in development - that the code is looking for specific files at startup if app.Environment.IsDevelopment() - when every other type of project in the polyglot workspace is probably only looking for environment variables when it runs.

All of this is not to say that there aren't situations where dotenv-net is the right solution. It's just that in general I prefer not to use it, for reasons given.

Why I moved from AutoFixture to Bogus for test data generation in C#/xUnit tests

Naveed Ausaf — Sat, 05 Jul 2025 16:03:39 +0000

AutoFixture and Bogus are both well-known libraries for generating test data in C# tests. AutoFixture is dated, whereas Bogus is state-of-the-art.

I moved to Bogus from AutoFixture because:

AutoFixture is dated and no longer under active development. Releases are infrequent (last one was 8 months before the date of this writing). Documentation was updated in 2021 and many of the links mentioned in it contain very old posts.
AutoFixture is too basic. I was quite surprised to discover that despite how long it's been around, there seems to be no out of the box way of generating a number in a specified range.

This makes it particularly difficult to use with Price for example which is bounded by zero below and would typically have an upper limit also.

Bogus is a .NET port of Faker, a JavaScript test data generation library, and it does not have the problems above:

it is actively developed
has brilliant documentation
has a flexible and powerful API which allows you to generate (semi-)meaningful test data within specified constraints really easily. Also, the code you write to do so would be a pleasure to read.

Given a Product class that looks like this:

public class Product
{
    public int Id { get; set; }
    public required string Name { get; set; }
    public required string Description { get; set; }
    public required string ImageUrl { get; set; }
    public required decimal Price { get; set; }

}

this is what a Faker for the class looks like:

internal class ProductFaker : Faker<Product>
{
    public ProductFaker()
    {
        RuleFor(p => p.Id, f => f.Random.Int(1, int.MaxValue));
        RuleFor(p => p.Name, f => f.Commerce.ProductName());
        RuleFor(p => p.Description, f => f.Lorem.Paragraph());
        RuleFor(p => p.ImageUrl, f => f.Image.PicsumUrl());
        RuleFor(p => p.Price, f => f.Finance.Amount(0, 5000));

    }
}

Using ProductFaker, you can generate endless amounts of random, yet semi-meaningful Product objects to use in your tests.

And that Image.PicsumUrl() call generates URLs to actual images on https://picsum.photos that you can navigate to in your Playwright or Selenium tests!

What's really great is that GitHub Copilot generated (almost all of) the ProductFaker for me, as soon as I typed : Faker<Product>. On the other hand when I was wrestling with AutoFixture, it was quiet. This may have something to do with how much Bogus-based (and possibly Faker-based; Bogus is a port of Faker.js) test code there is out there that LLMs have been trained on.

Nick Chapsas has an excellent video, Generating realistic fake data in .NET using Bogus, demonstrating the use of Bogus.

Intercepting HTTP Traffic from the Console with Fiddler

Naveed Ausaf — Tue, 01 Jul 2025 00:48:13 +0000

Fiddler doesn't work out of the box with HTTP traffic originating from commands run in the terminal (like curl). Luckily, it can be configured to do so.

The configuration given below would allow you to both intercept such traffic and decrypt SSL requests and responses.

Configure Fiddler and your terminal

I tested these steps on Fiddler Classic, which is quite old (but free!) but they should work on the newer, flashier Fiddler Everywhere also:

Click Tools | Options menu to bring up the Options dialog. Go to Connections tab:

Make sure the two checkboxes highlighted in red are checked.

Take note of the port on which Fiddler listens (8888 in my case).
Go to your terminal and run the following commands (I am using export keyword for Bash, you might need to use set for Windows shells):
```
export http_proxy=127.0.0.1:8888
export https_proxy=127.0.0.1:8888
```
This needs to be done every time you open a terminal from which you want HTTP traffic to be intercepted.
Run a command on the terminal that executes an HTTP request e.g.:
```
curl --ssl-no-revoke -H "Accept: text/plain" https://icanhazdadjoke.com/ 
```
With curl you have to use the --ssl-no-revoke option, for reasons explained shortly.
You should now see traffic to the site accessed by curl, but it would be encrypted.
To descrypt SSL traffic, you need can click the yellow button shown in the snapshot above. This would bring up Tools | Options dialog again, this time at the HTTPS tab.

Configure it as follows (you can play around with the settings):

Try out the setup

Try the curl command given above again. You should now be able to see the decrypted SSL traffic of further requests:

Why we need to use `--ssl-no-revoke` with cURL

Fiddler is a man-in-the middle. This is what allows it to sniff HTTP traffic and show it to us. To decrypt SSL/TLS traffic Fiddler, issues and uses its own SSL certificate to interface with the client (e.g. the curl command in the example above).

This works fine with many terminal commands that make HTTP calls, for example terraform apply which makes API calls. However, curl throws an error, which I believe is because it actually checks if the certificate that Fiddler is using to establish the TLS tunnel is legit (which it is not, in the sense that it has not been issued by a well-known certificate authority such as VeriSign).

Using the --ssl-no-revoke command line parameter with curl gets around the error.

An attempt to return meaningful Problem Details responses for model binding errors in an ASP.NET Core Minimal API

Naveed Ausaf — Tue, 19 Nov 2024 18:04:55 +0000

Introduction

Model Binding is the process of binding parameters of the route handler to values provided in the request (to route segments, query string parameters, cookies, request headers or request body) or to services in the DI container.

The automatically added EndpointMiddleware, which is the last middleware in the request pipeline, performs model binding, then invokes the handler for the requested route with the parameter values extracted during model binding.

If an error occurs during model binding, then in Production environment, EndpointMiddleware returns a 400 or a 500 response with an empty response body whereas in Development environment it throws a BadHttpRequestException.

I like to return error conditions from my minimal API handlers as responses that are compliant with the IETF Problem Details specification. I do this because it is a well-crafted yet really lightweight standard for returning errors from REST APIs. It is also mature (now in its second iteration) and ASP.NET Core has good support for it.

I wanted to do the same with model-binding errors also: to return helpful and detailed ProblemDetails responses that would help the client fix an error that had occurred during model binding, instead of the EndpointMiddleware default of a 400 response with empty body in Production environment.

In order to do this I needed to understand exactly how EndpointMiddleware returns an error that it encountered during model binding.

How EndpointMiddleware returns Model Binding Errors

I have verified the following behaviour:

If a model binding error occurred but NOT due to an issue with contents of the HTTP request, then the EndpointMiddleware would return a 500 status code.

This would happen in both Production and Development environments i.e. regardless of whether app.Environment.IsProduction() or app.Environment.IsDevelopment() is true in Program.cs at runtime.

An example is when a service that was meant to be resolved from the DI container and passed in as an argument to the handler could not be resolved. No exception would be throw, only 500 would be set as the status code of HttpContext.Request

On the other hand, if the error occurred due to an issue with contents of the request, for example:

a required field or value is missing in the request
a request parameter has a value that is invalid/malformed or of an incorrect data type
there is an issue with JSON request body (e.g. it is malformed)

then the response from EndpointMiddleware varies by environment:

In Development environment (and possibly in any non-Production environment), a BadHttpRequestException is thrown by the middleware.
This has:
- StatusCode property set to 400
- a Message property that is informative such as:
  
  Failed to read parameter "CreateProductArgs createProductArgs" from the request body as JSON.
- InnerException property which, if there was problem deserializing the JSON request body, would be System.Text.Json.JsonException.
  
  Again, this has an informative Message property:
```
JSON deserialization for type 
'problemdetailstestapi.CreateProductArgs' was 
missing required properties, 
including the following: price
```
But in Production Environment, the EndpointMiddleware sets status code 400 in the outgoing response with a blank response body.

However we can enable throwing of BadHttpRequestException in Production environment by adding the following line in Program.cs before builder.Build() is called (from this issue in dotnet/aspnetcpore repo) to get our hands on the information that this exception would contain in Development:
```
builder.Services.Configure<RouteHandlerOptions>(
  options => { options.ThrowOnBadRequest = true; }
);
```
Now, even in Production, if a model binding error occurred due to an issue with contents of the request, then a BadHttpRequestException would be thrown by EndpointMiddleware. This is useful as the exception can be quite informative.

Clearly, the messages above in BadHttpRequestException are useful but cannot be sent back to the client verbatim as doing so would reveal internal execution and implementation details.

I also do not want to parse them to extract information as for the same exception, the structure of the error message can be different in different sitautions. Also, exception messages may change in the future.

However, the messages are very useful for logging, and that alone is a good reason to turn on throwing of BadHttpRequestException in Production environment (i.e. to catch and log the exception).

I have verified that an error does not get logged at level Information or above (using .NET logging) from within EndpointMiddleware if there is a model binding exception when binding the request. Now, even if it does log at level Debug or below, I don't want to turn on such verbose logging in Production for any part of the request pipeline on an permanent basis.

So we need to log this exception ourselves. This can be done in one of at least two ways:

via request logging at the reverse proxy (e.g. in a Web App in Azure App Service) to log all requests that resulted in a 400 response being returned. Here, bear mind that even though the EndpointMiddleware would throw a BadHttpRequestException up the the middleware chain, what gets returned to the client - what exits the pipeline as response - is a plain 400 with empty body.
by writing a middleware that will catch and log the BadHttpRequestException exception thrown by EndpointMiddleware once throwing of this exception has been turned on in Production environment.

Returning model binding errors as Problem Details responses

Based on the above behaviour, I thought I could create and return informative Problem Details responses in the event of a model binding error by creating a middleware that would also log these exceptions using .NET logging, as follows:

Enable throwing HttpBadRequestException in Production environment.
Add a middleware just before RoutingMiddleware. This would catch catch a BadHttpRequestException.
If a BadHttpRequestException exception is caught in our middleware which was thrown by the EndpointMiddleware rather than by an endpoint filter or by the invoked router handler then we have one of these two error situations:

A. If InnerException is System.Text.Json.JsonException then the request body is invalid in the specific sense that either a provided value is of an incorrect type, or a required value is missing. Report this with a ProblemDetails response.

B. Otherwise the issue is with some other part of the request. Examples include the following: the JSON body is missing altogether, a required route segment is missing or has an invalid value. Report this with a ProblemDetails response.
If a BadHttpRequestException was NOT caught in the middleware that was thrown by the EndpointMiddleware, i.e. no exception was caught, or an exception was caught but it was not BadHtpRequestException or a BadHttpRequestException was caught but it hadn’t been thrown by the EndpointMiddleware (i.e. had ben thrown by an endpoint filter or from somewhere in the invoked route handler), then we do not have the information to create a meaningful ProblemDetails response.

So we just let it - the response or the exception - propagate up the request pipeline. Eventually it would be caught and, in Production environment, returned as a 400 response with blank body.

Was it worth it?

I did create the middleware to do the above (given at the end of this post) but the results were underwhelming.

It is at points 3A and 3B above that we detect model binding errors and where we could formulate and return meaningful Problem Details.

However at these points it is not possible to reliably parse the BadHttpRequestException thrown by EndpointMiddleware to extract details about where in the request the model binding errors occurred or why.

The issue is that the BadHttpRequestException thrown by EndpointMiddleware on model binding errors is not very machine readable. Therefore I could not formulate and return meaningful Problem Details responses that could pinpoint the error and provide detail to help the client fix it.

Instead, all I can return are two very broad errors, one at 3A and another at 3B (shown in middleware code below). These cover, between them, pretty much everything that could go wrong with a request (headers, route segments, query string, request body, cookies). This is to say that the semantics of a 400 (Bad Request) status code are almost the same as these two errors (returned as Problem Details responses) taken together.

This begs the question: Is there any value in returning two very generic Problem Details responses, over returning a plain 400 with an empty response body?

The Problem Details specification offers an answer. To quote my favourite part of the spec:

truly generic problems -- i.e., conditions that might apply to any resource on the Web -- are usually better expressed as plain status codes. For example, a "write access disallowed" problem is probably unnecessary, since a 403 Forbidden status code in response to a PUT request is self-explanatory.

Conclusion

I don’t see what value distinguishing between these two broad errors would add over just sending back a plain 400 with an empty response body.

And in Production environment, a plain 400 with an empty response body is exactly what gets returned on a model binding error. So there's no need to do anything or change anything.

In particular, I will not implement the solution above.

In order to get more specific errors out of the opaque model-binding process, I would need to basically reverse-engineer (at least partially) EndpointMiddleware's model-binding logic in the custom middleware.

I am not particularly inclined to do this either because I cannot see how the value of this to the consumers of my current API project exceeds the investment in reverse-engineering the model-binding logic, and keeping it in sync with future ASP.NET Core releases.

Isn't the whole point of model-binding in ASP.NET Core that it is free compared to something like Express/Node.js?

However I would always want to have logging of model-binding errors so I could inspect them later. This might lead me to precise model-binding errors that are worth reporting from a middleware as ProblemDetails responses in the future.

To get this logging there are two broad options:

turn on request logging in the reverse proxy to log all requests that led to 400 responses with empty bodies (these would include those that were returned by the EndpointMiddleware on model binding errors.
My Preferred Option: Use a custom middleware to log BadHttpRequestException thrown from EndpointMiddleware.
You can adapt the middleware shown below to do this and place it - by calling the UseXXX method to register it - as follows:
- If you do not have app.UseRouting() or app.UseEndpoints() in your Program.cs then place it at the very end of middleware registrations, before the first app.MapXXX call. This is because in minimal API, since at least .NET 9+, app.Run() automatically add the Routing and Endpoints middlewares at the end if they haven't been registered explicitly.
- If you do have either app.UseRouting or app.UseEndpoints() in your Program.cs then add the middleware just before both of those.

The middleware was as follows.

It doesn't include the check for the stack trace to see if the BadHttpRequestException was thrown by the EndpointMiddleware or not; I give a sketch of how to do this further down.

You can try it out in your own ASP.NET Core minimal API app by calling ProblemDetailsForBadRequestMiddlewareExtensions.UseProblemDetailsForBadRequest in your Program.cs. I did this by adding line app.UseProblemDetailsForBadRequest() after line var app = builder.Build(); in the boilderplate code but before app.UseRouting();. If you do not have app.UseRouting(); of app.UseEndpoints(); (these are not necessary in .NET minimal APIs any more) then simply add it as the last middleware before the first app.MapXXX() method call in your Program.cs.

The process of creating and using a custom middleware is described here in ASP.NET Core documentation.

using System.Text;
using System.Text.Json;

namespace problemdetailsmiddleware.Middleware;

public class ProblemDetailsForBadRequestMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ProblemDetailsForBadRequestMiddleware> _logger;

    public ProblemDetailsForBadRequestMiddleware(RequestDelegate next, ILogger<ProblemDetailsForBadRequestMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (BadHttpRequestException ex)
        {
            context.Response.StatusCode = 200;
            await context.Response.WriteAsync(ex.StackTrace ?? "");
            return;

            context.Response.StatusCode = ex.StatusCode;
            _logger.LogError(ex, "BadRequestException occurred while processing HTTP request");
            if (ex.InnerException is JsonException)
            {
                //this would only happen if the 
                // var validationProblem = TypedResults.ValidationProblem(new Dictionary<string, string[]> {
                //     {"request body json", new string[] {@"An error occurred when parsing the provided request body. One of three things is likely to be wrong:

                //     1. The provided request body is not well-formed JSON
                //     2. A required key is missing in the request body JSON
                //     3. A value of an incorrect type is provided for a key in the request body JSON"}}
                // });

                var problem = TypedResults.Problem(
                    statusCode: StatusCodes.Status400BadRequest,
                    type: "http://example.com/problems/invalid-request-body-json",
                    title: "\"An error occurred while parsing request body JSON\","
                    detail: "Request body was provided but an error occurred when parsing it. One of three things is likely to be wrong: 1. The provided request body is not well-formed JSON 2. A required property is missing in the request body JSON 3. A value of an incorrect or incompatible type was provided for a property in the request body JSON"
                    );

                await problem.ExecuteAsync(context);
            }
            else
            {
                var problem = TypedResults.Problem(
                    statusCode: StatusCodes.Status400BadRequest,
                    type: "http://example.com/problems/missing-body-or-invalid-request-parameter-values",
                    title: "\"Request body is missing or a request parameter value is missing or invalid\","
                    detail: "Either the request body is required but missing, or the value of a request parameter - in request headers, query string, route segments or cookies - is either missing ( in case of a required parameter) or invalid (e.g. of an incorrect type). Check your request against the OpenAPI description of the operation."
                );
                await problem.ExecuteAsync(context);
            }
        }
    }

}


public static class ProblemDetailsForBadRequestMiddlewareExtensions
{
    public static IApplicationBuilder UseProblemDetailsForBadRequest(this IApplicationBuilder builder)
    {
        return builder.UseMiddleware<ProblemDetailsForBadRequestMiddleware>();
    }
}

Distinguishing between whether the BadHtpRequestException was thrown from EndpointMiddleware of from further down the request processing pipeline:

If every frame in the stack (each is a new line) begins with at Microsoft.AspNetCore.Http.RequestDelegateFactory until potentially a --- End of stack trace from previous location --- line is ensountered, then the exception was thrown from EndpointMiddleware (I believe RequestDelegateFactory create a RequestDelegate out of every middleware in the pipeline that is to be invoked). For example,

   at Microsoft.AspNetCore.Http.RequestDelegateFactory.Log.InvalidJsonRequestBody(HttpContext httpContext, String parameterTypeName, String parameterName, Exception exception, Boolean shouldThrow)
   at Microsoft.AspNetCore.Http.RequestDelegateFactory.<HandleRequestBodyAndCompileRequestDelegateForJson>g__TryReadBodyAsync|102_0(HttpContext httpContext, Type bodyType, String parameterTypeName, String parameterName, Boolean allowEmptyRequestBody, Boolean throwOnBadRequest, JsonTypeInfo jsonTypeInfo)
   at Microsoft.AspNetCore.Http.RequestDelegateFactory.<>c__DisplayClass102_2.<<HandleRequestBodyAndCompileRequestDelegateForJson>b__2>d.MoveNext()
--- End of stack trace from previous location ---
   at problemdetailsmiddleware.Middleware.ProblemDetailsForBadRequestMiddleware.InvokeAsync(HttpContext context) in C:\MyWork\problemdetails\problemdetailsmiddleware\Middleware\ProblemDetailsForBadRequestMiddleware.cs:line 20

If there are other frames, theses would come from an endpoint filter or from somewhere in the invoked route handler. In this case, not all frames, until the line --- End of stack trace from previous location --- is encountered, would start with at Microsoft.AspNetCore.Http.RequestDelegateFactory, as in this example from a Release build of a minimal API (for some reason the Release build also contained a .pdb, hence the topmost frame even tells youthat the error occurred at line 80):

   at Program.<>c.<<Main>$>b__0_3(IList`1 products, LinkGenerator linkGen, CreateProductArgs createProductArgs) in C:\MyWork\problemdetails\problemdetailsmiddleware\Program.cs:line 80
   at lambda_method4(Closure, EndpointFilterInvocationContext)
   at FluentValidation.AspNetCore.Http.FluentValidationEndpointFilter.InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
   at Microsoft.AspNetCore.Http.RequestDelegateFactory.<ExecuteValueTaskOfObject>g__ExecuteAwaited|129_0(ValueTask`1 valueTask, HttpContext httpContext, JsonTypeInfo`1 jsonTypeInfo)
   at Microsoft.AspNetCore.Http.RequestDelegateFactory.<>c__DisplayClass102_2.<<HandleRequestBodyAndCompileRequestDelegateForJson>b__2>d.MoveNext()
--- End of stack trace from previous location ---
   at problemdetailsmiddleware.Middleware.ProblemDetailsForBadRequestMiddleware.InvokeAsync(HttpContext context) in C:\MyWork\problemdetails\problemdetailsmiddleware\Middleware\ProblemDetailsForBadRequestMiddleware.cs:line 20

Creating an NPM package that runs on command line

Naveed Ausaf — Wed, 02 Oct 2024 16:59:10 +0000

Every now and then I need to create an NPM package that runs on the command line, as a CLI (Command Line Interace).

For example, npx eslint runs and lints code in a directory and can accept command line arguments also. Similarly npx create-next-app --eslint --tailwind would scaffold a Next.js app that has eslint and tailwind configured.

There are three things you need to do to turn an NPM package into one that can be run from the command line:

Create a file that contains the code that would run when the package is run using npx from the command line, e.g. cli.js.
In package.json, place a "bin" field:
```
"bin": "./cli.js",
"type": "module",
```
"bin": "./cli.js" tells npx that when the package is run from the command line using npx <package name>, then ./cli.js should be run.

ASIDE: "type": "module" tells NPM utilities that the type of modules which would be imported in the code files in this package would be ES6 (using import statement). Otherwise you would only be able to import Common JS modules (using require) which, this being the tail-end of 2024, you probably don't want to do.

On top of the file declared in "bin" in package.json, place the line #!/usr/bin/env node. This allows the cli.js to run using the Node.js executable when it is launched by npx.

For example, my cli.js in package root would look like this:

#!/usr/bin/env node
import { createRequire } from "module";
const require = createRequire(import.meta.url);
const packageJson = require("./package.json");

console.log("Hello World!");
console.log(`Version number of the package is ${packageJson.version}`);

If I publish the package to NPM by running npm publish on the terminal in the project folder, then go to a completely different folder on the terminal and execute npx show-version-number (where show-version-number is the name of the package in package.json and therefore in NPM registry), it would still run:

I checked that npx downloaded and stored the package in C:\Users\{My User Name}\AppData\Local\npm-cache\_npx\ on my Windows machine.

Code is in this GitHub repo. If you want to publish it to NPM, please change "name" in package.json to a different value as I have already published a package with the name "show-version-number". I use this tool to check if a package name is available in NPM registry.

You can also create named commands by creating named values in "bin" in package.json like this:

"bin": {
  "showver": "./cli.js",
}

Now when you publish the package to NPM, and run it as npx show-version-number on the command line, cli.js would still run as before. I believe npx <package name> picks up the first entry in "bin" (in this case the key "showver") and runs the code file defined there (in this case ./cli.js).

However, you can also install the package on your machine:

npm install --global show-version-number

The npm install --global command would register a command named showversion with the operating system (as a cmd file on Windows and as a symlink on Unix-based system such as Linux, as described here) that aps to cli.js file.

Now, you can say the following on the terminal in any folder on your machine:

showver

This would run cli.js with Node executable and you would have the same output as when you ran npx show-version-number.

Of course, a single package may provide multiple named commands.

ASIDE: I had to import package.json using the following lines in cli.js:

import { createRequire } from "module";
const require = createRequire(import.meta.url);
const packageJson = require("./package.json");

instead of import packageJson from "package.json" because in my version of Node (v20+), this latter import throws a ERR_IMPORT_ASSERTION_TYPE_MISSING error when I try to run the package using npx ..

To fix the error I had to either rewrite the import as:

import packageJson from "./package.json" with { type: "json" };

or using the assert keyword as:

import packageJson from "./package.json" assert { type: "json" };

In either case, I got the following warning when I ran the code:

However, the three lines I use to import package.json instead, clunky as they are, get rid of the warning. See this StackOverflow thread for more details.

Environments in GitHub (with example of deploying a Next.js app to Vercel)

Naveed Ausaf — Mon, 30 Sep 2024 00:09:32 +0000

An Environment in GitHub is basically a set of three things:

Secrets
Variables
Protection rules

When you define an environment, you provide a name and can configure any of the above.

For example, when defining an environment named UAT (in Environments tab in repo Settings), the environment definition page would look like this:

What is interesting is that you can reference an environment in a job in a GitHub Actions workflow using an environment block like this:

jobs:
  deploy-to-vercel-pr-preview-env:
    runs-on: ubuntu-24.04
    environment:
      name: Preview
      url: ${{ steps.deploy-artifacts.outputs.previewUrl }}

In addition to the fact that such a job is allowed to access Variables and Secrets defined within the environment (as opposed to at the repo level) and Protection Rules such as delayed execution, manual approval, and deployment only from branches meeting specified criteria (e.g. with matching names and/or with branch protection rules) apply, when a job references an environment, this enables a number of other interesting behaviours:

There is a really nice sticky comment on the PR (so it updates with every push to the source branch if that triggers the CI workflow) which shows the value of the url property for the environment once the job has completed:
You can use check Require deployments to succeed before merging in a branch protection rule on the base branch (say main). This would ensure that any head branch (source branch) in a PR has successfully deployed to the the specified environment.

Deployment of the source branch to an environment is indicated by there being a job in a workflow that runs on the source branch which references the specified and provides a deployment URL. An example can be seen in the snippet above in which job deploy-to-vercel-pr-preview-env has an envionment object that specifies name: Preview and also sets the value of the url property which would be the URL to which the job deployed.

I am not sure of the value of this check in simple branching workflows as you would already have a check in branch protections rules on main (or other base branch) to say that a certain job ran successfully. One such job would be the one that deploys to a UAT or other pre-release environment successfully (e.g. deploy-to-vercel-pr-preview-env in the snippet above).
The url property of environment can be static but it can also reference a step output parameter of the same job. In the latter case, the url property of the environment block in the job will be evaluated after the step which outputs that parameter value has executed.

In the job snippet shown above, the step that produces the referenced step output parameter is:
```
id: deploy-artifacts
    run: |
      previewUrl=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})
      echo "previewUrl=$previewUrl" >> "$GITHUB_OUTPUT"
```
Once the job has completed (or perhaps when the step above has completed), value of step output parameter previewUrl would be available. This would be assigned to url proeprty of the environment. This is what gets displayed on the sticky comment for the environment as the deployment URL
If a job referencing an environment runs on multiple source branches (in multiple PRs), they don't seem to wait for each other i.e. they seem to run in parallel (I might be wrong on this).

In this case each would post a different URL in its sticky comment as long as the underlying deployment logic generated a different URL on every deployment. For example, every deployment of Next.js project to Preview environment in your Vercel project would generate a new URL.

In fact, since Vercel has such a generous allowance of deployment to an environment that would keep active, all deployments of the same branch, within the same pull request are active and accessible. If your deployment job references a GitHub environment (e.g. "Preview" in above example) then all of these deployment URLs are accessible on the pull request, not just the latest one:

All deployments to an environment, with their respective URLs if provided, can also be seen on repo main page in a section on right hand side named Deployments:

You can click an environment name and see a list of all deployments to it, including link to each. The link to the most recent deployment is shown right at the top:

To use GitHub Environments in my Next.js project which I deploy to Vercel, I do the following:

Create two GitHub Environments, named Production and Preview.

A Vercel project to which the repo is deployed also has evironments with the same names (these are Vercel environments though, not GitHub environments). So its good to have matching names in both GitHub repo and Vercel project.

My CI workflow deploys a pull request's source branch to Vercel's Preview environment and references GitHub Environment named "Preview":

name: CI
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true
permissions:
  checks: write
  pull-requests: write
on:
  pull_request:
    branches:
      - main
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy-to-vercel-preview-env:
    name: Deploy to Vercel Preview environment
    runs-on: ubuntu-24.04
    environment:
      name: Preview
      url: ${{ steps.deploy-artifacts.outputs.previewUrl }}
    steps:
      - uses: actions/checkout@v2
      - name: Install Vercel CLI
        run: npm install --global vercel@latest
      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build Project Artifacts
        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy Project Artifacts to Vercel
        id: deploy-artifacts
        run: |
          previewUrl=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})
          echo "previewUrl=$previewUrl" >> "$GITHUB_OUTPUT"

Release/CD workflow that deploys main to Vercel Production environment references the GitHub Environment named "Production":

name: Release to Production
concurrency: release-to-prod-pipeline
on:
  push:
    branches:
      - main

jobs:
  deploy:
    name: Deploy to Vercel
    runs-on: ubuntu-24.04
    environment:
      name: Production
      url: ${{ steps.deploy-artifacts.outputs.previewUrl }}
    env:
      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
    steps:
      - uses: actions/checkout@v2
      - name: Install Vercel CLI
        run: npm install --global vercel@latest
      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy Project Artifacts to Vercel
        id: deploy-artifacts
        run: |
          previewUrl=$(vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }})
          echo "previewUrl=$previewUrl" >> "$GITHUB_OUTPUT"

Set up linting and formatting for code and (S)CSS in Next.js with ESLint, Stylelint, Prettier and lint-staged

Naveed Ausaf — Wed, 26 Apr 2023 21:20:21 +0000

UPDATE: Please find an up to date version of this article on FreeCodeCamp.

Replacement for retired VS Code Jest codelens

Naveed Ausaf — Fri, 30 Dec 2022 23:32:54 +0000

The Codelens provided by VS Code Jest extension on tests in the editor has been retired (hence this post on Jest CodeLens I wrote a while back is also outdated).

The fix is really simple:

In your User Settings file (setttings.json), put this line in:

"testing.defaultGutterClickAction": "contextMenu"

You should now be able to access Debug test etc. from the Play button in the gutter:

VS Code Jest extension: tackling Debug codelens disappearing act

Naveed Ausaf — Tue, 18 Oct 2022 16:24:03 +0000

This is the section of my VS Code User Preferences settings.json (to access, Ctrl +P then select Preferences: Open User Settings) for Jest VS Code extension:

{
    ...
    "jest.coverageFormatter": "GutterFormatter",  
    "jest.debugCodeLens.showWhenTestStateIn": [
        "fail",
        "unknown",
        "pass",
        "skip"
    ]
}

I found that the Jest extension's Debug CodeLens wouldn't always appear on tests. A lot of the time I had to go to Testing window in VS Code sidebar to start debugging on a test because the Debug codelens wasn't available on the test in situ in the code file.

Turns out this was because jest.debugCodeLens.showWhenTestStateIn has default value of ["fail", "unknown"].

I added the other two possible statuses to ensure that the Debug codelens is always available.

The other setting here is jest.coverageFormatter. I find seeing coverage in the gutter on the left of a file unobtrusive compared to the extension's default behaviour of colour-coding regions of code in the file.

You can of course set the above on a per project basis by putting the snippet above in .vscode\settings.json in your workspace (this file can be created/navigated to using the command Ctrl + P then Preferences: Open Workspace Settings).

Configure different Jest timeouts for unit and integration tests in the same project

Naveed Ausaf — Mon, 17 Oct 2022 21:54:21 +0000

The Problem

You want to configure different test execution timeouts for Jest tests in different folders in the same project e.g. 1 second for tests in ./tests/unitTests/ and 60 seconds for tests in ./tests/integrationTests.
During debugging, the timeout for tests in any folder should be quite large, say 10 minutes.

Otherwise Jest could throw timeout errors like thrown: "Exceeded timeout of 5000 ms for a test. even if a test completes successfully. This happens when debugging a test takes longer than the (default or explicitly configured) timeout for it.

Solution

Given the folder structure:

.
│   jest.config.js
│   package-lock.json
│   package.json
│
└───tests
    ├───integrationTests
    │       integrationTestSuite.test.js
    │
    └───unitTests
            unitTestSuite.test.js

a solution is as follows:

npm install --save-dev debugger-is-attached
Create a jestSetup.js file in each of the test folders and set the desired timeout via a call to jest.setTimeout() method.
So we have a tests/unitTests/jestSetup.js file:
```
jest.setTimeout(1000); //timeout of 1 second
```
and a tests/integrationTests/jestSetup.js file:
```
jest.setTimeout(60000); //timeout of 1 minute
```

Create jest.config.js in project root as follows

const { debuggerIsAttached } = require("debugger-is-attached");
const path = require("path");

module.exports = async () => {
  const isDebuggerAttached = await debuggerIsAttached();

  const unitTestFolder = "<rootDir>/tests/unitTests";
  const integrationTestFolder = "<rootDir>/tests/integrationTests";
  const getSetupFiles = (folder) =>
    isDebuggerAttached ? [] : [path.join(folder, "jestSetup.js")];

  const baseProjectConfig = {
    //Here put any properties that are the same for
    //all folders and can be specified at level
    //of the project object (all such properties
    //are declared in type ProjectConfig in
    //Config.ts in Jest repo)
  };

  let config = {
    //any config key/values in configuration (except those
    //that are to specified in ProjectConfig)
    //e.g. 
    //collectCoverage: true,

    //project config
    projects: [
      {
        ...baseProjectConfig,
        displayName: "UnitTests",
        testMatch: [path.join(unitTestFolder, "**/*.test.js")],
        slowTestThreshold: 1000, //1 second
        setupFilesAfterEnv: getSetupFiles(unitTestFolder),
      },
      {
        ...baseProjectConfig,
        displayName: "IntegrationTests",
        testMatch: [path.join(integrationTestFolder, "**/*.test.js")],
        slowTestThreshold: 60000, //1 minute
        setupFilesAfterEnv: getSetupFiles(integrationTestFolder),
      },
    ],
    //any other Jest config goes here
    //(these are any properties declared in type
    //InitialConfig but not in type ProjectConfig
    //in Config.ts in Jest repo)
  };

  if (isDebuggerAttached) config["testTimeout"] = 600000; //ten minutes

  return config;
};

In User Settings (settings.json which appears when from the Ctrl + P command pallette you select Preferences: Open User Setting (JSON)), set "jest.monitorLongRun" to a value that is equal to or greater than the largest of the folder-specific timeouts declared in jest.config.js above. For example,
```
"jest.monitorLongRun": 60000, //1 minute
```

Explanation

Configuring different timeouts for different test folders

testTimeout property can be set in jest.config.js in project root to set a timeout other than the default of 5s:

module.exports = {
    ...
    testTimeout: 60000; //60 seconds
};

How to specify testTimeout separately for different subfolders?

The canonical way to assign different configurations to tests in different subfolders is to use Jest's monorepo configuration. We pretend, as far as Jest is concerned, that folders tests/integrationTests and tests/unitTests are two separate projects in a monorepo (a collection of related projects stored in a single repository).

Using this approach we can configure separate timeouts for our two subfolders as follows:

Create a jest.config.js in each subfolder. In this set testTimeout property as shown in the snippet above.

Declare the different folder-specific config files as projects in the top-level jest.config.js:

module.exports = {
  projects: [
    "<rootDir>/tests/unitTests/jest.config.js",
    "<rootDir>/tests/integrationTests/jest.config.js",
  ],
};

At this point the folder structure would be as follows:

.
│   jest.config.js
│   package-lock.json
│   package.json
│
└───tests
    ├───integrationTests
    │       integrationTestSuite.test.js
    │       jest.config.js
    │
    └───unitTests
            jest.config.js
            unitTestSuite.test.js

The problem is that if we configure testTimeout property in a folder-specific config file it will not have any effect.

This is because testTimeout is not defined in type ProjectConfig in Config.ts which specifies the config schema of project (which for use are the two subfolders of tests).

Even though the top-level as well as folder-specific config files are all called jest.config.js, the properties that are allowed in folder level config are not all the same as the properties allowed in top level config.

Folder-specific config files need to have be those defined in type ProjectConfig whereas top-level jest.config.js specifies properties that are probably declared in type InitialConfig in Config.ts.

Many keys are defined in both types but not testTimeout: it is only contained in InitialConfig and therefore only has effect if declared in the top-level config file.

Therefore testTimeout property cannot be use to override test timeouts in jest.config.js files in subfolders.

Instead, to set timeout at subfolder level:

We can call jest.setTimeout(TIMEOUT_IN_MS) in a .js file in the subfolder, conventionally named jestSetup.js.
Declare jestSetup.js in the folder-level jest.config.js so that it would be run by Jest before any tests in that folder are executed.

For example create tests/integrationTests/jestSetup.js as follows:

jest.setTimeout(60000); //timeout of 1 minute

and a tests/integrationTests/jest.config.js to go with it:

module.exports = {
  displayName: "IntegrationTests",
  setupFilesAfterEnv: [`<rootDir>/jestSetup.js`],
};

For unit tests, ./tests/unitTests/jest.config.js would be the same as the config file for integration tests folder shown above (because <rootDir> always resolves to the containing folder). However ./tests/integrationTests/jestSetup.js would specify a different timeout:

jest.setTimeout(1000); //timeout of 1 second

The folder structure of this working solution looks like this:

.
│   jest.config.js
│   package-lock.json
│   package.json
│
└───tests
    ├───integrationTests
    │       integrationTestSuite.test.js
    │       jest.config.js
    |       jestSetup.js
    │
    └───unitTests                 
            jest.config.js
            jestSetup.js
            unitTestSuite.test.js

We can eliminate folder-specific jest.config.js files by pulling the info in the top level config so the ./jest.config.js in the root now looks like this:

module.exports = {
  projects: [
    {
      displayName: "UnitTests",      
      testMatch: ["<rootDir>/tests/unitTests/**/*.test.js"],
      setupFilesAfterEnv: ["<rootDir>/tests/unitTests/jestSetup.js"],
    },
    {
      displayName: "IntegrationTests",
      testMatch: ["<rootDir>/tests/integrationTests/**/*.test.js"],
      setupFilesAfterEnv: ["<rootDir>/tests/integrationTests/jestSetup.js"],
    },
  ],
};

The folder structure of this more compact solution looks like this:

.
│   jest.config.js
│   package-lock.json
│   package.json
│
└───tests
    ├───integrationTests
    │       integrationTestSuite.test.js
    │       jestSetup.js
    │
    └───unitTests
            jestSetup.js
            unitTestSuite.test.js

I'd like to point out three improvements that can be made:

It is worth adding a slowTestThreshold property in every project object and set it equal to or somewhat greater than the timeout declared in the corresponding jestSetup.js.

A longer timeout prevents Jest from throwing an error on longer running tests. But it would still show the execution time of such a tests with a red background:

Adding slowTestThreshold: 60000 to the folder's config in jest.config.js tells Jest that this is how long you expect tests in that folder to take so it doesn't show execution times in warning colour.
If a property is exported both ProjectConfig and InitialConfig types then, if you configure it in top level jest.config.js but not in folder-level config, it would be overridden by project config to its default value which would probably be null or undefined.

For example given a jest.config.js that looks like this:
```
module.exports = {
    setupFiles = ['./topLevelSetupFile.js'],
    ...

    projects: [
        {
            displayName: "IntegrationTests",
            testMatch: ["<rootDir>/tests/integrationTests/**/*.test.js"],
            setupFilesAfterEnv: ["<rootDir>/tests/integrationTests/jestSetup.js"],
        }
    ];
};
```
In the effective folder-specific configuration for folder ./tests/integrationTests/, setupFiles property would be set to nothing (null I think).

A nice solution (from Orlando Bayo's post) is to set the shared config - properties that are shared across all folders - in a baseProjectconfig object and spread this into every project object.

Incorporating both of these improvements into our solution, we have the following jest.config.js:

const baseProjectConfig = {
    //Here put any properties that are the same for
    //all folders and can be specified at level
    //of the project object (all such properties
    //are declared in type ProjectConfig in
    //Config.ts in Jest repo)
  };

  let config = {
    //any config key/values in configuration (except those
    //that are specified in ProjectConfig)
    //e.g. 
    //collectCoverage: true,

    //project config
    projects: [
      {
        ...baseProjectConfig,
        displayName: "UnitTests",
        testMatch: [path.join(unitTestFolder, "**/*.test.js")],
        slowTestThreshold: 1000, //1 second
        setupFilesAfterEnv: getSetupFiles(unitTestFolder),
      },
      {
        ...baseProjectConfig,
        displayName: "IntegrationTests",
        testMatch: [path.join(integrationTestFolder, "**/*.test.js")],
        slowTestThreshold: 60000, //1 minute
        setupFilesAfterEnv: getSetupFiles(integrationTestFolder),
      },
    ],        
    //any other Jest config goes here
    //(these are any properties declared in type
    //InitialConfig but not in type ProjectConfig
    //in Config.ts in Jest repo)
  };

module.exports = config

Jest VS Code extension still shows a popup if a test takes too long to execute (although, because of the configuration above, the test won't fail on a timeout):

To prevent this warning window from popping up, set "jest.monitorLongRun" in User Setting file (to edit it select Preferences: Open User Settings from Ctrl + P command pallette) to the value of the longest of your folder-specific timeouts e.g.:
```
"jest.monitorLongRun": 60000, //1 minute
```

Setting a long timeout when debugging

When debugging, if you take longer to step through a test than the (default or explicitly configured) timeout, Jest would throw a timeout error at the end even if the test completed successfully. I find that for a test to fail like this is confusing when you're debugging a test that you expect to pass.

To address this issue we can use the debugger-is-attached package. This exports an async function that returns true if debugger is attached and false otherwise.

It can be integrated into jest.config.js by exporting an async function that returns the config object instead of directly returning the object in question.

const { debuggerIsAttached } = require("debugger-is-attached");

module.exports = async () => {
    //do async things
    ...
    return {
        //the config object
    }
}

Inside the function, if the debugger is not attached then everything should be the same as before but if it is attached, then we make two changes to the returned object:

not configure jestSetup.js, the file that declares the timeout for tests in its containing folder, to run.
set testTimeout property to 10 minutes (600000 ms) to give us plenty of time to debug a test.

After these changes, the final top-level jest.config.js is as shown in TL;DR at the top.

Thanks for reading. Any comments or suggestions for improvement would be greatly appreciated.

Forem: Naveed Ausaf

OpenAPI in .NET 10: From Setup to Build-Time Generation (with Scalar UI)

Why OpenAPI and Build-Time Generation Matter

Sample Code

Set up OpenAPI document generation and Scalar UI

Note: Other ways of adding OpenAPI metadata to your project

Set up Build-time Generation of OpenAPI JSON document

The Problem with Runtime-Only Generation

Set up Build-time Generation

Other things you can do with your OpenAPI document

Conclusion

Patterns for Routing in ASP.NET Minimal APIs

How Routing Works in ASP.NET

1. The Startup Phase: Registration

2. The Runtime Phase: The Middleware Pipeline

Sample Code

Pattern 1: Handlers class

Implementation

Benefits

Pattern 2: Name Handlers for Reverse Routing

Implementation

Benefits

Pattern 3: Routing without Validation

Benefits

Pattern 4: Prefer the "Double Star" Catch-all

Benefits

Conclusion

Use .env files for .NET local development configuration with VS Code

The Problem with .NET Development Configuration

Step 1: Create .env files for VS Code launch configurations

Step 2: Provide an .env file to dotnet CLI commands

Additional Tips

Why I don't use dotenv-net

Why I moved from AutoFixture to Bogus for test data generation in C#/xUnit tests

Intercepting HTTP Traffic from the Console with Fiddler

Configure Fiddler and your terminal

Try out the setup

Why we need to use --ssl-no-revoke with cURL

An attempt to return meaningful Problem Details responses for model binding errors in an ASP.NET Core Minimal API

Introduction

How EndpointMiddleware returns Model Binding Errors

Returning model binding errors as Problem Details responses

Was it worth it?

Conclusion

Creating an NPM package that runs on command line

Environments in GitHub (with example of deploying a Next.js app to Vercel)

Set up linting and formatting for code and (S)CSS in Next.js with ESLint, Stylelint, Prettier and lint-staged

Replacement for retired VS Code Jest codelens

VS Code Jest extension: tackling Debug codelens disappearing act

Configure different Jest timeouts for unit and integration tests in the same project

The Problem

Solution

Explanation

Configuring different timeouts for different test folders

Setting a long timeout when debugging

Step 1: Create `.env` files for VS Code launch configurations

Step 2: Provide an `.env` file to `dotnet` CLI commands

Why I don't use `dotenv-net`

Why we need to use `--ssl-no-revoke` with cURL