Read Testing AI prompts and comparing models with promptfoo on timdeschryver.dev

As AI becomes more integrated into our daily workflows, we start to see that applications also increasingly rely on prompts to make certain tasks easier or more efficient.

However, prompts may not always have the expected outcome. Even the most basic prompts can produce unexpected results, and small changes can introduce regressions that are hard to detect without systematic testing. Not only changes to the prompt itself, but also changes to the model, or changing the model itself, can affect the output quality and cost.

Just like other software components, prompts benefit from tests that provide representative inputs to verify that the outputs meet the requirements.

Why automate prompt testing

When an application uses only one prompt, it's manageable to test it manually and optimize it until the prompt produces the expected output for various scenarios. However, this process should be repeated when the prompt changes or when a different model is used. As the number of prompts and criteria grows, manual verification quickly becomes time-consuming, and difficult to repeat consistently within a team.

Promptfoo automates this process by running a set of prompts and inputs against an AI model. It evaluates the responses using predefined assertions, making it easier to repeat the same checks after every change. This ensures that the prompt continues to meet the requirements and that the output quality is not compromised due to different factors.

Compare models without sacrificing quality

Next to testing prompt behavior, promptfoo makes it easier to compare and evaluate multiple models. Automated evaluations help catch regressions, and it also helps when the application switches to another model. This is important because models can behave differently and may require different prompts to achieve comparable results.

Even the smallest subtle change in a prompt can have a significant impact on the output quality, and it can be difficult to determine whether a different model is suitable without running the same tests against it.

Running the same test cases against multiple models lets you compare output quality, token usage, and cost. This is critical to determine whether a cheaper model meets the same requirements, and to switch models without unknowingly sacrificing quality.

Promptfoo also supports multiple providers, so you can compare models from different vendors within the same evaluation.

What can you test?

With promptfoo, you can define prompts and create test cases for the given prompts. Each test case provides assertions that describe the expected output, and can include variables to add dynamic content to the prompt. Promptfoo renders the prompt, sends it to every configured model, and evaluates each response.

The assertions broadly fall into two categories: deterministic assertions and model-graded assertions.

Deterministic assertions

Deterministic assertions evaluate a response using explicit rules. Given the same response and assertion, they always produce the same result. They are useful when the requirement can be expressed precisely, for example:

• Comparing the output with an expected value using equals, contains, not-contains, or a regular expression.
• Verifying the response length with word-count.
• Validating structured output, such as JSON that must match a JSON schema.
• Comparing semantic similarity using vector embeddings.

When the multiple built-in assertions are not sufficient, you can also implement a custom rule with JavaScript, Python, or Ruby. E.g. for complext JSON schemas, you can write a zod schema validator.

Not only can you check the correctness of the output, but you can also verify that it meets performance requirements with assertions to check to cost, latency, and token usage.

These assertions are usually the best starting point because their results are predictable and easy to debug.

See the Deterministic metrics documentation for the complete list.

Model-graded assertions

Some requirements are difficult to describe with an exact rule. Model-graded assertions use another language model as a judge to evaluate more subjective qualities, such as:

• Whether the response uses the expected tone or writing style.
• Whether an answer is relevant, complete, and appropriate for its audience.
• Whether a summary preserves the important information.
• Whether the response follows a natural-language rubric or remains factually consistent with a reference.

Use them for requirements that genuinely need judgment, and prefer deterministic assertions wherever an explicit rule is sufficient.

A thing to watch out for, because model-graded assertions require an additional model call and can be less predictable than deterministic checks, they also add latency and cost.

See the Model-graded metrics documentation for the available graders.

A practical promptfoo example

Promptfoo evaluations are defined in a configuration file containing the models, prompt, test inputs, and assertions. This makes the evaluation repeatable and ensures that every model receives the same inputs and is measured against the same expectations.

In this example, promptfooconfig.yaml tests a practical data-extraction task: extracting information from fictional customer messages and returning it as structured JSON. This scenario is useful because the output must satisfy both strict requirements, such as valid JSON, and qualitative requirements, such as not inventing information that is missing from the message.

The configuration compares GPT-5.6 Luna, the efficient tier, with GPT-5.6 Sol, the flagship tier.

The test cases use a mix of a deterministic and model-graded assertions to verify that the output is valid JSON, contains the expected keys, and does not invent values that are not present in the source message.

Instead of defining the configuration in YAML, you can also define it in TypeScript, as shown as well in the example below. The TypeScript version produces the same test cases programmatically, which can be useful when test data needs to be transformed or generated.

In the prompt, variables can be inserted using the Nunjucks template syntax, for example, a placeholder such as {{text}} is replaced with the matching value from vars before the prompt is sent to a model.

 promptfooconfig.yaml 
prompts:
  - |
    Extract the person's name and email address from the following message.
    Respond with a JSON object containing only the keys "name" and "email".
    Do not infer values that are not explicitly present.
    Use an empty string when a value is not present.
 
    {{text}}
 
providers:
  - openai:responses:gpt-5.6-luna
  - openai:responses:gpt-5.6-sol
 
defaultTest:
  assert:
    - type: is-json
      value:
        type: object
        required:
          - name
          - email
        additionalProperties: false
        properties:
          name:
            type: string
          email:
            type: string
    - type: llm-rubric
      value: |
        Compare the response with the following source message:
        {{text}}
 
        Pass only when every non-empty name and email address in the
        response is explicitly present in the source message. The response
        must not invent values.
    - type: cost
      threshold: 0.005
 
tests:
  - vars:
      text: 'Hi, my name is Alex Johnson. Contact me at alex.johnson@example.com.'
    assert:
      - type: is-json
        value:
          properties:
            name:
              const: 'Alex Johnson'
            email:
              const: 'alex.johnson@example.com'
  - vars:
      text: 'Please send the invoice to Priya Shah at priya.shah@example.org.'
    assert:
      - type: is-json
        value:
          properties:
            name:
              const: 'Priya Shah'
            email:
              const: 'priya.shah@example.org'
  - vars:
      text: 'I cannot access my account after resetting the password.'
    assert:
      - type: is-json
        value:
          properties:
            name:
              const: ''
            email:
              const: ''

 promptfooconfig.ts 
import type { UnifiedConfig } from 'promptfoo';
 
const cases = [
  {
    name: 'Alex Johnson',
    email: 'alex.johnson@example.com',
    text: 'Hi, my name is Alex Johnson. Contact me at alex.johnson@example.com.',
  },
  {
    name: 'Priya Shah',
    email: 'priya.shah@example.org',
    text: 'Please send the invoice to Priya Shah at priya.shah@example.org.',
  },
  {
    name: '',
    email: '',
    text: 'I cannot access my account after resetting the password.',
  },
];
 
const config: UnifiedConfig = {
  prompts: [
    `Extract the person's name and email address from the following message.
Respond with a JSON object containing only the keys "name" and "email".
Do not infer values that are not explicitly present.
Use an empty string when a value is not present.
 
{{text}}`,
  ],
  providers: [
    'openai:responses:gpt-5.6-luna',
    'openai:responses:gpt-5.6-sol',
  ],
  defaultTest: {
    assert: [
      {
        type: 'is-json',
        value: {
          type: 'object',
          required: ['name', 'email'],
          additionalProperties: false,
          properties: {
            name: {
              type: 'string',
            },
            email: {
              type: 'string',
            },
          },
        },
      },
      {
        type: 'llm-rubric',
        value: `Compare the response with the following source message:
{{text}}
 
Pass only when every non-empty name and email address in the response is
explicitly present in the source message. The response must not invent values.`,
      },
      {
        type: 'cost',
        threshold: 0.005,
      },
    ],
  },
  tests: cases.map(({ name, email, text }) => ({
    vars: {
      text,
    },
    assert: [
      {
        type: 'is-json' as const,
        value: {
          properties: {
            name: {
              const: name,
            },
            email: {
              const: email,
            },
          },
        },
      },
    ],
  })),
};
 
export default config;

In the example above, the shared assertions are defined once under defaultTest, while each test case provides a different text and a content-specific assertion.

Each text is evaluated against both models using the inherited and test-specific assertions, making it easy to compare output quality and cost across a broader set of inputs.

You can also notice that Nunjucks variables can also be used in assertion values. In this exmaple, the llm-rubric assertion uses {{text}} to provide the grading model with the source message.

Load prompts and variables from files

As the test suite grows, keeping prompts and test data in separate files makes them easier to maintain and reuse. The customer-message example from the previous section can be refactored into the following feature-based structure:

 
promptfoo
├── customer-message
│   ├── fixtures
│   │   └── customer-message.txt
│   ├── prompts
│   │   └── extract-personal-information-v1.txt
│   ├── tests
│   │   └── extract-personal-information.yaml
│   └── promptfooconfig.yaml
└── providers.yaml

The feature's promptfooconfig.yaml references its prompt and test files using the file:// prefix, as well as the shared provider configuration one directory above it:

 [title=customer-message/promptfooconfig.yaml] 
prompts:
  - file://prompts/extract-personal-information-v1.txt
 
providers: file://../providers.yaml
 
defaultTest:
  assert:
    - type: is-json
      value:
        type: object
        required:
          - name
          - email
        additionalProperties: false
        properties:
          name:
            type: string
          email:
            type: string
    - type: llm-rubric
      value: |
        Compare the response with the following source message:
        {{text}}
 
        Pass only when every non-empty name and email address in the
        response is explicitly present in the source message. The response
        must not invent values.
    - type: cost
      threshold: 0.005
 
tests:
  - file://tests/extract-personal-information.yaml

The contents of these files are identical to the inline example, except that the prompt and test cases are now stored in separate files.

 providers.yaml 
 openai:responses:gpt-5.6-luna
 openai:responses:gpt-5.6-sol

 customer-message/prompts/extract-personal-information-v1.txt 
Extract the person's name and email address from the following message.
Respond with a JSON object containing only the keys "name" and "email".
Do not infer values that are not explicitly present.
Use an empty string when a value is not present.
{{text}}

 customer-message/tests/extract-personal-information.yaml 
 vars:
    text: file://fixtures/customer-message.txt
  assert:
    - type: is-json
      value:
        properties:
          name:
            const: 'Alex Johnson'
          email:
            const: 'alex.johnson@example.com'
 vars:
    text: 'Please send the invoice to Priya Shah at priya.shah@example.org.'
  assert:
    - type: is-json
      value:
        properties:
          name:
            const: 'Priya Shah'
          email:
            const: 'priya.shah@example.org'
 vars:
    text: 'I cannot access my account after resetting the password.'
  assert:
    - type: is-json
      value:
        properties:
          name:
            const: ''
          email:
            const: ''

 customer-message/fixtures/customer-message.txt 
Hi, my name is Alex Johnson. Contact me at alex.johnson@example.com.

In this example, promptfoo loads the customer message from the fixture instead of embedding it in the configuration. All file:// paths are resolved relative to promptfooconfig.yaml, regardless of the directory from which the command is run.

Compare multiple prompts for the same task

When two prompts solve the same task, add both prompt files to the same configuration:

 
prompts:
  - file://prompts/extract-personal-information-v1.txt
  - file://prompts/extract-personal-information-v2.txt

By default, promptfoo runs every test against every prompt and provider. This is useful for comparing prompt variants because each combination receives the same inputs and assertions.

Organize different tasks by feature

As an application grows, it will probably contain different types of prompts for unrelated tasks with different variables and expectations. In that case, I prefer to use a separate configuration for each task instead of placing every prompt and test in one configuration.

A larger test suite could use the following structure:

 
promptfoo
├── customer-message
│   ├── fixtures
│   │   └── customer-message.txt
│   ├── prompts
│   │   ├── extract-personal-information-v1.txt
│   │   └── extract-personal-information-v2.txt
│   ├── tests
│   │   └── extract-personal-information.yaml
│   └── promptfooconfig.yaml
├── billing-request
│   ├── fixtures
│   │   └── billing-request.txt
│   ├── prompts
│   │   └── classify-support-request.txt
│   ├── tests
│   │   └── classify-support-request.yaml
│   └── promptfooconfig.yaml
└── providers.yaml

Each feature directory now contains its configuration, prompts, fixtures, and tests. This keeps files that change together close to each other while the model configuration remains shared. For example, customer-message/promptfooconfig.yaml can contain:

 
description: 'Extract personal information from customer messages'
 
prompts:
  - file://prompts/extract-personal-information-v1.txt
  - file://prompts/extract-personal-information-v2.txt
 
providers: file://../providers.yaml
 
tests:
  - file://tests/extract-personal-information.yaml

Both feature configurations can reference the root-level providers.yaml shown earlier, ensuring that every task evaluates the same models.

Run one task while working on a specific prompt (more on this in the next section):

 
pnpm exec promptfoo eval --config promptfoo/customer-message/promptfooconfig.yaml

Or run every configuration to evaluate the complete prompt suite:

 
pnpm exec promptfoo eval --config promptfoo/*/promptfooconfig.yaml

This structure keeps prompts, inputs, and assertions close to their use case while still making model selection reusable across the entire suite.

Set up promptfoo

If you're hooked and want to try promptfoo yourself, you can follow the steps below to set up the example from this post. Promptfoo can be installed as a development dependency. The examples below use pnpm:

 
pnpm add --save-dev promptfoo

You can then use the interactive setup to create an example promptfooconfig.yaml file with minimal effort. In the wizard pick the option "Compare prompts and models".

 
pnpm exec promptfoo init

You can run the example, or replace the generated YAML configuration with the example above, or adapt it to your own prompts and test cases. To use TypeScript instead, create promptfooconfig.ts from the TypeScript example.

Each model provider requires its own credentials. For the OpenAI providers in this example, make OPENAI_API_KEY available in your environment. Keep the key outside the configuration file and do not commit it to source control.

Run the tests

For a YAML configuration, run the evaluation from the directory that contains promptfooconfig.yaml:

 
pnpm exec promptfoo eval

Promptfoo runs every test case against each configured prompt and model. The terminal displays a table with the generated outputs and shows which assertions passed or failed.

While changing a prompt or its assertions, watch mode automatically starts a new evaluation when the configuration changes:

 
pnpm exec promptfoo eval --watch

View the results

To inspect the results in the web viewer, run:

 
pnpm exec promptfoo view

The viewer opens a local web application where you can compare model outputs side by side, inspect failed assertions, and review token usage, latency, and cost. Previous evaluations are also available, which makes it possible to compare the results before and after changing a prompt or model.

The results can also be written to a standalone HTML file:

 
pnpm exec promptfoo eval --output results.html

This gives you the following results for the example evaluation.

Conclusion

In this post, we used promptfoo to test a personal-information extraction prompt with deterministic and model-graded assertions, and to compare the same results across multiple models. We also saw how to define evaluations in YAML or TypeScript, and how to scale this using a feature-based folder structure and by loading prompts and variables from files.

Prompt testing is valuable because it turns assumptions about model behavior into repeatable checks. Start with a few representative inputs and assertions for the most important requirements, then add new test cases whenever an unexpected response or regression is discovered.

It also helps to reduce costs by comparing models and prompts, and by tracking token usage and latency. Once the same evaluation suite can run against multiple models, changing models becomes a measurable decision instead of a manual experiment. You can compare quality alongside token usage, latency, and cost, and choose a smaller or cheaper model with confidence that it still meets the application's requirements.

As next steps, the same evaluations can also run as part of a CI/CD pipeline, where they can catch prompt or model regressions before a change is deployed. This is very similar to your current test suites.

Instead of a local workflow, with the setup and files located in a source control repository, you can also opt to use the web version of promptfoo, which provides a shared interface for creating, running, and sharing evaluations. This is also useful to share evaluations within your team on a central location, and to keep track of the evaluation history. This is available via the Promptfoo app in Promptfoo Cloud or a self-hosted instance.

Promptfoo can also do more than the prompt and model comparisons covered in this post. This is definitely worth exploring if AI is heavily integrated into your application, e.g. for red-teaming and security testing or evaluating model security.

Alternatives

Promptfoo is not the only option for evaluating prompts and AI applications. Depending on the application's technology stack and whether evaluation needs to be connected to production observability, the following alternatives are also worth considering:

• Langfuse combines evaluation with tracing, prompt management, datasets, and production observability. It supports offline experiments for comparing prompt or model versions, as well as online evaluations of live application traces, making it a good fit when evaluation should be part of a broader LLM observability workflow. You can also use Langfuse prompts within promptfoo evaluations, which makes it possible to combine the two tools.
• The .NET Microsoft.Extensions.AI.Evaluation libraries provide a code-first option for .NET applications. They integrate with test frameworks such as xUnit, NUnit, and MSTest, and include quality, natural language processing (NLP) metrics, safety.

Read the code-only version on timdeschryver.dev

What and Why

The Model Context Protocol (MCP) gives AI clients a standardized way to connect with external tools outside of the chat window's context. These tools can come in different flavors, most commonly they read from external systems to enrich a prompt with structured data.

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems.

Creating your own MCP server allows you to expose your application's data and logic to AI clients. This seemless integration lets you interact with your application in a more natural way, using natural language instead of technical API calls. If you're already leveraging AI, it also automates certain tasks, e.g. instead of manually copy-pasting data into a prompt to provide context, the client can call an MCP tool to automatically retrieve the relevant information it needs. If your tool allows schedudeled tasks, the AI client can also call your tool to perform actions on your behalf.

With ASP.NET you can create your custom MCP tools using the ModelContextProtocol.AspNetCore NuGet package.

In this post, we'll build a small HTTP-based MCP tool that exposes a search tool for AI clients, just to give you a quick idea of how it works.

TLDR: writing an MCP tool is almost identical to building a regular web API endpoint, but it uses the MCP SDK to handle the request and response format for you.

When to use it

Instead of building a traditional (UI) application, you can build an MCP server to expose the internals of your application directly to AI clients. This allows you to leverage the power of AI models to interact with your application. In other words, it gives your prompt a window into your application, so it can retrieve data and perform actions on your behalf.

This can be useful in many scenarios. Personally, I think it can help to reduce the friction of interacting with your application, and make complex screen flows more accessible. We recently used it to query data by asking "normal" questions instead of building a complex filter UI. It can also be helpful to quickly instruct an action to be performed.

Setup in ASP.NET

Follow along to create a new ASP.NET application and add the MCP server capabilities to it.

First start by creating a new ASP.NET application:

 
dotnet new web -o CatalogMcpServer
cd CatalogMcpServer

In the ASP.NET application, add the ModelContextProtocol.AspNetCore NuGet package:

 
dotnet add package ModelContextProtocol.AspNetCore

Then, in the Program.cs file, add the MCP server to the service collection and configure the MCP server to work over HTTP:

• AddMcpServer() registers the MCP server to the service collection with default options.
• WithHttpTransport() adds the services necessary for McpEndpointRouteBuilderExtensions.MapMcp to handle MCP requests and sessions using the MCP Streamable HTTP transport.
• WithToolsFromAssembly() scans the assembly for MCP tool classes (more on this later). If you want, you can also register your tools manually using WithTools<ToolType>() instead.
• MapMcp() exposes the MCP endpoint over HTTP, and we set it to the path /mcp.

 Program.cs 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services
    // Adds the Model Context Protocol (MCP) server to the service collection with default options.
    .AddMcpServer()
    // Adds the services necessary for McpEndpointRouteBuilderExtensions.MapMcp to handle MCP requests and sessions using the MCP Streamable HTTP transport.
    .WithHttpTransport()
    // Manually register your MCP tools.
    .WithTools<CatalogTools>();
    // Adds types marked with the ModelContextProtocol.Server.McpServerToolTypeAttribute attribute from the given assembly as tools to the server.
    .WithToolsFromAssembly();
 
var app = builder.Build();
 
app.MapMcp("mcp");
 
app.Run();

Your first MCP tool

So far, we have created an ASP.NET application and added the MCP server to it. Now let's create a tool that can be called by AI clients.

For example, let's create a tool that allows AI clients to search for products in a catalog. To keep the example compact, we're using a in-memory list of products, but in a real application you would query your database or call an external service.

To create the tool, create a new class CatalogTools and mark it with the McpServerToolType attribute, this is important so it is automatically discovered.

Within the class create your tool method and mark it with the McpServerTool attribute. The method can be asynchronous and return any serializable type, in this case we return a list of products.

 CatalogTools.cs 
using System.ComponentModel;
using ModelContextProtocol.Server;
 
[McpServerToolType]
public sealed class CatalogTools
{
    [McpServerTool, Description("Searches products in the catalog by name.")]
    public static async Task<IEnumerable<ProductResult>> SearchProducts(
        [Description("Part of the product name, for example 'smartphone'. If not provided, all products will be returned.")]
        string? query)
    {
        return new[]
        {
            new ProductResult(1, "Keyboard", 10, 99.99m),
            new ProductResult(2, "Mouse", 25, 49.99m),
            new ProductResult(3, "Monitor", 0, 399.99m),
            new ProductResult(4, "Smartphone", 5, 899.99m),
        }.Where(p => query == null || p.Name.Contains(query, StringComparison.OrdinalIgnoreCase));
    }
}
 
public record ProductResult(int Id, string Name, int Stock, decimal Price);

As you can see, the tool, and the parameters, are decorated with the Description attribute, which is used by the MCP server to generate a description of the tool and its parameters. This description is sent to the client when it connects, so it knows what tools are available and how to call them.

A McpServerTool method can have any number of parameters, and the parameters can be of any serializable type. The MCP server will automatically serialize the parameters to JSON and deserialize them back to the method parameters when the tool is called.

The McpServerToolType can also have multiple tools defined in the same class.

To test the server, start your application with dotnet run.

 
dotnet run

How it translates a prompt to a request

When the MCP client connects to our server, it asks the server the tools that are available. In this case it connects to the Catalog server and it discovers the product search tool (search_products).

When a user asks a question in the chat window, the client uses all of this information to determine which tool to call and with which parameters. It uses the description of the tool and its parameters to understand how to call the tool and provide the right arguments. That's why it's important to provide a good description of the tool and its parameters, ideally with some examples, as it helps the client understand how to call the tool and provide the right arguments.

Let's take a look at a concrete example, and let's say we ask the question "Do we sell keyboards?" in the chat window of the AI client:

 
Do we sell keyboards?

The client detects that the context is about our catalog, and it knows about the Catalog tool. If it doesn't automatically detect the tool, you can also explicitly tell the client to use the tool. With that knowledge, it translates the given question into a request that our server expects and understands, in this case it invokes the search_products tool with a JSON payload containing the query parameter set to "keyboard":

 
{
  "query": "keyboard"
}

ASP.NET receives the tool call, the MCP SDK invokes SearchProducts, and the client receives the result. The model then uses that result to formulate a suitable answer.

Based on the result the model either:

• Answers the question directly when it has enough information;
• Uses the result to extract the relevant information and answer the question;
• Invokes other tools until it has enough information to answer the question.

Based on the question and the result, the AI model decides how to structure and format the answer in a way that is most useful to the user. It can for example just answer the question, or display a collection as a table.

In the case of our example, the model uses the result to answer the question directly:

 
Yes, we sell keyboards

Or it can even add extra information, like the stock and price of the product:

 
Yes — we sell Keyboard.
    Stock: 10
    Price: $99.99

Installing the MCP server with an AI client

To make the MCP server available to AI clients, we need to add the server to the list of available MCP servers. Depending on the AI client you are using, this can be done in different ways. Some clients allow you to add the server to a configuration file, while others allow you to add it via a UI (this can also be named plugins, extensions, ...).

In the following example, we add a new entry to the .mcp.json file in the root of the project, as this file is generic and can be used by multiple AI clients (GitHub Copilot, Codex, OpenCode) to discover available MCP servers.

 .mcp.json 
{
  "mcpServers": {
    "catalog": {
      "type": "http",
      "url": "<ASP.NET URL>/mcp"
    }
  }
}

Because we made the MCP server available over HTTP, we register it as an HTTP server with the URL of the endpoint we mapped in Program.cs.

After adding the server to the configuration file, you might also need to "start" the MCP tool. Again, this is different depending on the tools you are using, and whether you are registering the MCP server as part of a project workspace or if it's available globally.

In VS Code, there will be a lightbulb above the "catalog" entry in the .mcp.json file, click "Start" to start the server and make it available to the chat window of VS Code.

After these steps, you should see that the client can discover the catalog MCP server, together with the available tools and their descriptions.

Result

You can now ask questions about the catalog products, and the client should call the search_products tool to retrieve the relevant information.

In the chat history you can notice that the client calls the search_products tool, and if you click on it you can also verify the raw input and outputs. The model then uses that result to formulate a suitable answer.

Conclusion

In this blog post, we've built a small HTTP-based MCP server with ASP.NET that gives you a quick idea of how you can build your own MCP server, and how AI clients communicate with it.

MCP allows AI clients to use external systems outside of the chat window's context. A common use case is to retrieve relevant data from an external system.

This can be useful for your application, if you want to expose your application's data so your users can inquire about it in a more natural way via a chat window. While this was a simple example, in a real-world scenario, you would query your database or call an external service to retrieve the relevant information.

The next steps are to secure the MCP server with authentication. Since it's just an ASP.NET application, you can re-use the same techniques you would use to secure any other Web API application. You could for example add a Key header to the request and validate it using middleware.

Instead of making the MCP tool available via HTTP, you can also make it available as a CLI tool using WithStdioServerTransport() instead of WithHttpTransport(). This allows you to run the MCP server as a separate process and communicate with it via standard IO.

Read Using Agentic AI to create your own component library on timdeschryver.dev

Starting a new frontend project always comes with a set of decisions that shape the project in the long term. One of those key decisions is whether the team should use an existing component library or build its own.

For a long time, my default recommendation was simple: use an existing component library.

That advice still makes sense in many cases. Existing component libraries give you speed. They provide ready-to-use components with consistent behavior, (hopefully) accessibility considerations, and documentation including examples. For many teams, especially smaller teams, this is the most pragmatic choice.

But that choice also comes with a cost.

When you adopt a component library, you also adopt its assumptions. You get its generic API design, its look and feel, and a predefined behavior. You're also dependent on its release cycle and upgrade path, or lack of upgrade path. That is not necessarily a problem, but it's something to be aware of.

In practice, this friction doesn't always appear immediately.

At the start of a project, a component library usually feels like a productivity boost. You install it, add a few components, and quickly build screens that look consistent. Because most libraries have a lot of extra bells and whistles, you can often get a lot of functionality with minimal effort. You start to use it extensively, but as the product grows, the design requirements become more specific, and more custom to your needs. The product team wants a slightly different interaction than the standard. A flow requires specific behavior that does not fit the component's generic design.

When this happens, teams start to bend the component library to their specific needs, and this is where the cost starts to appear, and if done poorly, it can become a significant maintenance burden. Teams start to customize the library to fit their needs, using various techniques:

• they override CSS
• they create wrapper components to add missing features or to implement their own API on top of the library's API using their own defaults
• they reach into internals to tweak behavior

Teams do this to work around behavior that was not designed for their use case.

While this is not necessarily a problem, sometimes it is fine. But over time, those customizations can become expensive.

The more you deviate from the library's intended usage, the harder it becomes to upgrade. What started as a productivity gain can slowly turn into a dependency that is difficult to change. A major version update can quickly break a project. Every internal CSS class you relied on becomes a risk. Every wrapper component becomes a translation layer between your application and the library. This is when an upgrade path can become a long and expensive process, that requires buy-in from above.

This does not mean component libraries are bad. They are not, and they remain a good choice for many projects. But the decision is not free. You are trading control for convenience, and that trade-off can become more expensive the more your product diverges from the library's assumptions.

In this post I want elaborate that my point is not that every team should build its own component library. My point is that agentic AI lowers the cost of doing so, especially when combined with a source-owned component approach.

The traditional trade-off

When teams face this decision, the decision is often framed as a trade-off between control and convenience:

• Using an existing component library gives you speed and stability, but less control.
• Building your own component library gives you control and flexibility, but more responsibility, with a higher initial cost.

That responsibility is significant. A component library is not just a collection of buttons, inputs, and other UI elements. It is an internal product. It needs a good and consistent API, accessibility features, test coverage, documentation, and maintenance.

For smaller teams, that cost is often too high.

That is why I would usually advise against building your own component library unless there is a strong reason to do so. Most teams should not spend their time reinventing components when their actual goal is to build business value.

Over the past years, a third option has become more valid with the rise of utility-first CSS frameworks, and more specifically with Tailwind CSS. This recent frontend ecosystem shift has provided a good alternative to the traditional component library model.

A useful middle ground has emerged, and instead of consuming a component library as a black-box dependency, you pull the component source code into your own codebase. Instead of installing a component package within your node modules and treating it as an external runtime dependency, you copy the component code directly into your project as your own components. From that point on, you own the code, and you can modify it as needed.

This way of working, also called a code distribution platform, is successfully implemented and popularized by libraries such as shadcn/ui in the React ecosystem, and Spartan or Zard in the Angular ecosystems.

That model is interesting because it changes the ownership boundary.

You still avoid writing everything from scratch, and you get a solid foundation as a starting point. But you are not limited by an external package's public API, styling decisions, or release cycle. You can adapt the component to your application/product because you own the code. This gives you the flexibility to customize and extend behavior without fighting the library.

Agentic AI to increase the viability of custom component libraries

The biggest reason not to build your own component library has always been the time it requires to create and maintain it. This is time that is not spent building product features, and it is time that is not directly visible to stakeholders. This makes it a cost that can be difficult to justify.

Writing the first version is only part of the work. The real cost comes later: improving APIs, fixing edge cases, keeping components accessible, adapting them to new design requirements, adding tests, keeping it up to date with the latest Angular version and standards, and documenting its usage.

That cost does not disappear with AI, but it changes.

Agentic AI can help you with the repetitive, structural, and incremental work that made custom component libraries expensive in the past. An AI agent can generate a first implementation, refactor an API, add tests, improve accessibility, migrate code to a newer Angular pattern, or create examples based on existing components.

This does not mean that you can blindly outsource your component library to an AI agent. You still need technical ownership. You still need engineers who understand the architecture, review the output, and define the standards.

But the amount of effort required to create and evolve components is lower than it used to be.

That disrupts the traditional trade-off. The convenience of an existing component library is still there, but the cost of ownership for a custom component library is now lower. This makes the option of building your own more viable for more teams.

For some teams, building a custom component library is no longer an unrealistic investment. It can become a practical option, especially when done incrementally.

Instead of deciding upfront that you are going to build a complete component library, you can start with the components you actually need. With this incremental approach, you can let real application needs drive the component library. You can create components as patterns emerge in the application, and you can use AI agents to help with the implementation and maintenance work, one component at a time.

Take the AI-driven approach in combination with code distribution platforms, and it also works well. You can pull in the source code for a component, for the initial implementation, and then use AI agents to help customize it to your needs, and maintain it over time. You get the best of both worlds: a solid starting point and the flexibility to evolve it as needed. When the component doesn't fit your needs, you can also decide to rewrite it from scratch.

Benefits of owning your components

The main benefit of owning your components is control, and flexibility over styling, behavior, and API design.

Customization without fighting the library

Custom styling is one of the main sources of friction when using external component libraries.

Most teams eventually need to make components look and behave differently from the default. Some libraries provide strong theming support. Others are harder to customize. Even when customization is possible, you are still working within the constraints of the library's design.

Owning the component source code avoids much of that friction.

You do not need to override internal CSS selectors. You do not need to wrap a component just to change a small part of its template. You do not need to wait for a feature request to be accepted upstream.

You can change the component.

That does not mean every component should become a one-off implementation. The goal is still consistency. The difference is that the consistency is defined by your team instead of by an external package.

This is especially useful when you have a strong design system or a product with specific interaction patterns.

Your component library can reflect your product directly.

Control over API design

One of the most underestimated benefits of owning your components is control over the API surface.

A good component API should match how your team builds applications.

External component libraries need to support many use cases. That often leads to broad APIs with many inputs, configuration options, slots, templates, and extension points. This flexibility is necessary for a public library, but it can also make components harder to use.

An internal component library has a different goal.

It does not need to support every possible use case. It only needs to support your use cases.

That means your APIs can be smaller, more opinionated, and more aligned with your product. You can encode your design system directly into the components. You can remove options that should not be configurable. You can make the default path the correct path.

For example, instead of exposing every possible option, you can design a component API that matches your product language. Only if it's necessary, you can add a more flexible API for edge cases. But the main API can be simple and focused.

The component becomes part of your application architecture.

With agentic AI, you can also iterate on this API faster. You can ask an agent to inspect existing usage, identify inconsistencies, suggest a simpler API, and update all call sites. That kind of refactoring used to be tedious. It still requires review, but it is no longer as expensive.

How to make it work

You can build your own component library from scratch, or use a code distribution platform to pull in the source code of existing components. But this doesn't affect the core principles of how to make it work. The most important part is clear ownership over the components.

Incremental adoption

A common mistake is thinking about a component library as a large upfront investment.

That does not have to be the case.

A more practical approach is to build the library incrementally. Start with the smallest useful set of components and only add more when the application needs them. When creating the component don't try to predict every possible use case. Instead, focus on the most common patterns in your application and build components that support those patterns well.

This keeps the cost low.

You do not need to spend weeks up-front designing a complete library before building product features. You can extract components as more use cases appear. You can let the application needs drive the component creation and evolution over time.

This also prevents overengineering.

Many internal component libraries fail because they try to predict too much too early. They create abstractions for use cases that never appear. They introduce flexibility that nobody needs. This results in the library becoming a project inside the project.

A better approach is to start small.

Create components when duplication appears. Stabilize the API when usage becomes clear. Use AI agents to help with implementation, tests, documentation, and migrations.

This gives you control without turning the component library into a bottleneck.

Treat it as an external dependency

Even when the component source code lives in your repository, it helps to mentally treat the library as an external dependency to overcome the temptation to reach into internals.

That means application developers should not need to understand every internal detail of every component. The public API should be the main contract.

This can come across as bad advice. After all, you own the code and are responsible for it. If things go wrong, it's on you. But if the public API is designed properly, it gives you a stable surface to build on, while still allowing you to change the internals as needed, for example, when it becomes a problem.

This allows you to move fast, without discussing every internal detail every time you need to use a component.

When a component is well-designed, it should allow the internals to change, without affecting the public API. If the component behaves correctly, it shouldn't matter if the implementation can be slightly refactored. At least that's my opinion. I'm confident that when the component is small, that it can be refactored or rewritten without affecting the application code.

AI agents can help here as well. They can generate usage examples, detect breaking API changes, update call sites, and keep documentation aligned with implementation.

Accessibility still requires ownership

One of the risks of building your own component library is accessibility.

External component libraries often have accessibility built in, or at least they have spent time handling keyboard behavior, ARIA attributes, focus management, and screen reader support. When you build your own components, that responsibility moves to your team.

Again, AI can help here. An agent can suggest ARIA attributes, implement keyboard interactions, and compare components against accessibility patterns. That is useful. But accessibility is not something to blindly delegate.

You still need to validate behavior.

For Angular projects, a useful building block is the new @angular/aria package, which provides accessibility primitives that can be used in your components. These primitives are designed to follow best practices and can help reduce the risk of accessibility issues. The aria package provides directives to handle accessibility patterns, without affecting the visual styling. This allows you to create custom-styled components while still maintaining accessibility.

Angular Aria works well when you need accessible interactive components that are WCAG compliant with custom styling.

Examples include components such as autocompletes, selects, comboboxes, menus, accordions, and more. These components require more than visual styling. They need correct focus management, keyboard support, roles, labels, right-to-left languages, and interaction semantics.

These are exactly the areas where a custom component library can become risky if the team underestimates the complexity.

A valid approach is to combine AI assistance with established accessibility primitives, automated tests, manual verification, and code review.

Where AI agents help most

Agentic AI is useful because component libraries contain a lot of work that is structured and well-defined. It's also something very common across many teams, which means that the agent has enough training data to learn from, and enough context to understand the patterns.

For example, a coding agent can help to:

• generate an initial component implementation;
• create tests with interaction scenarios;
• add and validate accessibility features, such as ARIA attributes and keyboard support;
• write usage examples;
• update documentation;
• refactor APIs;
• migrate components to newer Angular APIs;
• align similar components with the same conventions;
• scan for inconsistent usage across the application.

How to set up the agent for success

To improve the quality and consistency of the output, it is important to provide the agent with enough context and constraints. If you want to use AI agents to help build a component library, define the rules first.

Use the Angular Agent Skills to give the agent a good understanding of Angular concepts and best practices. This will help the agent generate code that is consistent and qualitive. Also create your own design system skill, that explains your design system and conventions. This will help the agent generate components that fit your product's style, design tokens (e.g. colors, typography, spacing), and requirements. If you have team rules, also include these in a SKILL or add it to the instruction file, this can touch on folder structure, naming conventions, testing requirements, documentation format, and more.

These standards do not need to be perfect from day one. But they need to exist. AI agents are much more useful when they are constrained. A clear set of conventions improves the quality and consistency of the output. The less code, the better.

With this in place, when you ask the agent to create a new component, it has a target to follow, improving the overall quality and consistency of the generated code.

When not to build your own

Even with AI agents, building your own component library is not always the right choice.

An existing component library is still a better option when your team needs broad component coverage quickly, does not have strong design requirements, or cannot commit to owning UI infrastructure.

Complex components are also worth considering carefully.

For example, data grids, rich text editors, and charts are harder than they look. They contain many edge cases, performance considerations, and interaction details.

In those cases, using a specialized existing library may still be the better decision. The point is not to reject external dependencies. The point is to be intentional about where you want control.

You can also combine and mix both approaches. Use custom components for your core design system. Use existing libraries for complex specialized components. Wrap external dependencies only when the wrapper gives you a clear boundary and does not fight the underlying library.

A practical workflow

If you decide to build your own component library, the next question is how to do it in a way that is sustainable. A practical workflow for building an AI-assisted Angular component library could look like this.

Start by creating a dedicated library or folder for shared UI components. Define the public API and conventions. Add a few foundational pieces such as buttons, icons, form fields, labels, error messages, and layout primitives. You can also use existing libraries as a starting point, by pulling in the source code for some components, and then customizing them to fit your design system and API conventions.

Then use real product work to drive the next components.

When screens and flows need a repeated pattern, extract it. Ask the agent to generate the component based on existing conventions. Review the API before reviewing the implementation. Make sure the component is easy to consume.

Then ask the agent to add tests, examples, and documentation.

For accessibility-sensitive components, consider using Angular accessibility primitives where possible.

For more complex components, decide to add a dependency on an existing library. While choosing a library, consider that it fits your design system so it doesn't look out of place.

Finally, keep the component library healthy. When one component improves, let the agent inspect similar components and suggest consistent changes. When Angular introduces a new recommended pattern, use the agent to help migrate the library incrementally.

This creates a feedback loop.

The application drives the component library. The component library improves the application. The AI agent reduces the maintenance cost between both.

Conclusion

Choosing between an existing component library and writing a custom one used to be a fairly predictable decision.

For most teams, the existing library was the safer and faster choice. Building your own meant taking on too much implementation and maintenance work.

Agentic AI changes that. While code distribution platforms already made it more viable to build your own component library, AI agents make it more practical to maintain and evolve it over time.

AI can reduce the cost of creating components, but it does not remove the need for engineering ownership. Without standards, reviews and tests, it only helps you generate technical debt faster.

By taking on the cost of ownership you gain control and flexibility. You can create components that are tailored to your product's design and interaction patterns. An incremental component library becomes a realistic option for more teams.

This isn't a "or-decision" but a "both-and" approach. You can use existing libraries where it makes sense, use code distribution platforms to pull in source code for a solid starting point, use @angular/aria for accessibility primitives, use external libraries for complex components, and build your own where you see the most value in owning the code.

For Angular teams, this can be especially useful. You stay within the Angular ecosystem, rely on Angular migrations, own your API surface, and avoid being blocked by external library decisions.

The result is not that every team should build everything themselves.

The better conclusion is this: build where control matters, reuse where complexity is high, and let AI agents reduce the cost of maintaining the pieces you decide to own.

Read Running a production-like local environment with Aspire on timdeschryver.dev

Setting up a local development environment that behaves like production is often harder than it should be.

The application code might run fine locally, but the surrounding services are usually where the differences and problems appear. Databases, queues, caches, storage accounts, mail servers, identity providers and external APIs all have their own setup, configuration and lifecycle.

In many projects, this leads to (small) differences between local development and deployed environments. Those differences are easy to miss while building a feature. They usually become visible later, during testing, deployment or in the worst-case scenario, production environments.

The most common example is probably the database as it's a critical dependency for most applications. In my early days, a common approach was to use a shared development database for the entire team. That worked, but it also created conflicts. Developers could overwrite each other's data, migrations could get out of sync, and one small schema change could affect everyone else, it could even break the entire environment for everyone. This wasn't ideal, as it was a fragile setup that required constant communication and coordination. Later, with the popularity of containerization, local database instances became more common. That improved things because you could work in isolation, but it still required manual setup that every developer had to be aware of. You had to remember to run the database container, ensure it was up to date with the latest migrations, and handle any issues that came up with the local instance.

Other dependencies were even more challenging to run locally. Think about:

• mail systems
• blob storage
• queues
• caching layers
• identity providers
• external HTTP services

Because many of these services were difficult to replicate, we would implement workarounds to run the code. Some integrations could be disabled, teams relied on mocks and stubs, or used a shared resource (with the same issues as the shared database) to get by. Another possibility could be to update data, e.g. updating email addresses to prevent emails from being sent to real users in non-production environments.

While this works, it lowers the confidence that solutions that work locally also work in production environments. You are no longer testing the application in a context that behaves close enough to the real one. That can lead to surprises later on, when the code interacts with the real dependencies and the differences become apparent.

Because these workarounds were often implemented in an ad-hoc way within the application, they also added complexity to the codebase. It could even lead to accidental mistakes causing a big impact if gone wrong, where local environments accidentally hit production integrations, for example during debugging sessions. Or the other way around, when code running in production is not using the production systems.

Where Aspire helps

Aspire gives you a way to describe your application and its dependencies from one place: the AppHost.

Within the AppHost, you define the services your application needs. Aspire can then orchestrate those services for local development and wire the required connection information into the consuming projects.

That does not make your local environment identical to production, but it does make it much easier to run a production-like environment on your machine. It can also help to document the dependencies of your application, and visualize how the different pieces of a system interact with each other.

That distinction matters. A local emulator is still an emulator. A containerized dependency is still not the same as a managed cloud service. But for day-to-day development, it gives you a much better feedback loop than manually configured shared resources or incomplete mocks. This results in more confidence in your code and fewer surprises when you deploy.

Later on, that same application model can be published to a non-local environment, being a staging environment or production environment.

While the aspire team manages many integrations to help you run local integrations, Aspire also provides the flexibility to write your own custom integrations for any service you need. With that flexibility in place, it makes it possible that there is also a growing ecosystem of community integrations (thank you CommunityToolkit) to run a wide variety of dependencies locally.

Some typical examples:

• Databases: use the SQL Server or PostgreSQL integration to easily set up a local instance of your database with automated migrations, ensuring that you are always working with the latest schema changes.
• Caching: use the Redis integration to set up a local caching layer.
• Azure resources: use the Azure Storage integration to set up local instances using Azurite to emulate Azure Storage services.
• Mailing systems: use the Mailpit integration to set up a SMTP server for testing email functionality without sending emails to external recipients.
• Observability: if you want to use something different than the built-in dashboard, you can use the Elastic Stack or Seq integrations to set up local instances of these popular observability tools.
• Messaging: use the RabbitMQ, Kafka, or Azure Service Bus integrations to set up local instances of these messaging systems for testing and development.
• Identity providers: use the IdentityServer integration with Keycloak or Zitadel.

Example: Azure Blob Storage with Azurite

Let's make this more concrete with an integration of Azure Blob Storage as an example.

In this scenario, the application interacts with Azure Blob Storage to store and retrieve files. In production, this connects to the actual Azure Storage account. However, for local development, you want to avoid using shared cloud resources due to the isolation level, and potential costs.

With Aspire, you can model the Azure Storage dependency in the AppHost and run it locally through Azurite.

First, add the Azure Storage hosting integration to your AppHost project:

 
aspire add azure-storage

This will install the Aspire.Hosting.Azure.Storage package, which allows Aspire to connect and use the Azure Storage services.

Then define the storage resource in the AppHost.cs file:

 AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
var storage = builder
    .AddAzureStorage("storage")
    .RunAsEmulator(azurite =>
    {
        azurite
            .WithLifetime(ContainerLifetime.Persistent)
            .WithDataVolume();
    });
var blobs = storage.AddBlobs("blob-storage");
var filesContainer = storage.AddBlobContainer(
    "app-files",
    blobContainerName: "app-files");
 
builder
    .AddProject<Projects.Project_Api>("project-api")
    .WithReference(blobs)
    .WaitFor(filesContainer);
 
builder.Build().Run();

This does a few things:

• It defines an Azure Storage resource called storage.
• It runs that resource locally through Azurite.
• It adds a blob service resource called blobs.
• It adds a specific blob container called app-files.
• It references the blob service from the API project, so the API receives the required connection information through Aspire as environment variables.

The WithLifetime(ContainerLifetime.Persistent) and WithDataVolume() calls are useful during development. They make sure the Azurite container and its data survive across local runs, instead of starting from an empty state every time.

Consuming Blob Storage from the API

Inside the API project, add the Aspire Azure Blob Storage client integration:

 
dotnet add package Aspire.Azure.Storage.Blobs

Then register the client in Program.cs using the AddAzureBlobServiceClient method, specifying the same connection name as defined in the AppHost.

 Program.cs 
var builder = WebApplication.CreateBuilder(args);
 
builder.AddAzureBlobServiceClient(connectionName: "blob-storage");
 
var app = builder.Build();
 
app.Run();

The important part here is the connection name. The connectionName in the API project must match the blob resource name from the AppHost. In this example, that name is blob-storage.

Aspire then handles the configuration and interaction with the blob service for you. The API project does not need to know whether the blob service is backed by Azurite locally or by Azure Storage in another environment. For consumers of the blob service, it's just a blob client that can be used to interact with the blob storage, regardless of the underlying implementation.

Switching between local and Azure

For local development, Azurite is usually the right choice. For deployed environments, you probably want to connect to a real Azure Storage account.

Because we're using Aspire, the configuration is handled in the AppHost, without any changes needed in the consumer project(s). This makes it easy to switch between local and Azure environments because the logic is centralized in one place. You also don't have to worry about environment-specific branching in your application code.

One option is to use AsExisting when publishing, so the application connects to an existing Azure Storage account. Using the ExecutionContext allows you to conditionally configure the storage resource based on whether you are in publish mode or not.

 AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
var storage = builder.AddAzureStorage("storage");
 
if (builder.ExecutionContext.IsPublishMode)
{
    var existingStorageName = builder.AddParameter("existingStorageName");
    var existingStorageResourceGroup = builder.AddParameter("existingStorageResourceGroup");
 
    storage.AsExisting(existingStorageName, existingStorageResourceGroup);
}
else
{
    storage.RunAsEmulator(azurite =>
    {
        azurite
            .WithLifetime(ContainerLifetime.Persistent)
            .WithDataVolume();
    });
}
 
var blobs = storage.AddBlobs("blob-storage");
 
var filesContainer = storage.AddBlobContainer(
    "app-files",
    blobContainerName: "app-files");
 
builder
    .AddProject<Projects.Project_Api>("project-api")
    .WithReference(blobs)
    .WaitFor(filesContainer);
 
builder.Build().Run();

Using a connection string directly

Not all packages and integrations will have built-in support for the AsExisting method, or similar methods to connect to existing resources. For these cases you can provide the connection string to the resource manually.

For demo purposes, this is also a possibility for Azure Storage if you want to use the connection string directly instead of the AsExisting method.

Just as before, this logic is still centralized within the AppHost.

The difference, is that the connection string is provided directly as an environment variable to the API project when publishing, instead of configuring it through the built-in Azure Storage integration.

 AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
var api = builder
    .AddProject<Projects.Project_Api>("project-api");
 
if (builder.ExecutionContext.IsPublishMode)
{
    api.WithEnvironment(
        "ConnectionStrings__blob-storage",
        builder.Configuration["ConnectionStrings:blob-storage"]);
}
else
{
    var storage = builder.AddAzureStorage("storage")
        .RunAsEmulator(azurite =>
        {
            azurite
                .WithLifetime(ContainerLifetime.Persistent)
                .WithDataVolume();
        });
    var blobs = storage.AddBlobs("blob-storage");
    var filesContainer = storage.AddBlobContainer(
        "app-files",
        blobContainerName: "app-files");
 
    api.WithReference(blobs).WaitFor(filesContainer);
}
 
builder.Build().Run();

In this version, the API still uses the same connection name: blob-storage. If you're unsure about the environment variable name that is used, you can look at the Aspire dashboard, or check the documentation of the integration you're using to see how it configures the information for the consuming projects.

Why this is useful

The main benefit is not that Aspire magically removes all environment differences. You still have to make choices about how close your local environment is to production, and there are always going to be some trade-offs.

The benefit is that Aspire gives you control over those differences and makes it manageable. Dependencies are centralized and become visible in the application model.

Your local setup becomes consistent and repeatable. Developers have fewer manual steps and don't have to read extensive documentation files to get up and running.

Your application code doesn't get polluted with environment-specific branching logic for every integration. The application code can just consume the services it needs, and Aspire takes care of providing the right configuration for the environment it's running in.

Using the same application model, you can publish the same application to a non-local environment, but with different configurations for the dependencies. Again, without any code changes needed in the application projects.

With the many integrations available, it's easy to run a wide variety of dependencies locally, which gives you a much better feedback loop during the development process. You also don't need to know and share credentials or connection strings to connect to resources.

This makes the local environment reflect the real environment much better. This is crucial, as many bugs are not caused by business logic alone. They appear in the interaction between those integrations.

Conclusion

In my experience, a good local environment gives the entire team confidence, and allows them to move faster without worrying about breaking things for others or running into unexpected issues when deploying.

The local environment should be easy to start, easy to inspect and close enough to production to catch integration issues early.

Aspire helps by letting you model your application and its dependencies in one place. With its many (and growing list of) integrations, it gives you a flexible way to run local instances of your dependencies. Aspire also handles and maintains the integration with those external services, so you don't have to worry about the setup and configuration details.

Because the configuration is centralized in the AppHost, you can easily switch between local and production configurations without any code changes needed in your application projects.

That doesn't only make your local development less fragile, it also prevents bad deployments when new integrations are not properly configured.

This all prevents scenarios where "it works on my machine" is a common excuse for bugs that only appear in production, and it gives you confidence that your code works in the real environment as well as it works locally.

In this post we looked at Azure Storage as an example, but the same principles apply to any other dependency you have in your application. Aspire's flexibility and growing ecosystem of integrations make it a powerful tool for managing your local environment and ensuring that it behaves as close to production as possible.

Read Improve your AI coding agent with runtime context from Aspire MCP on timdeschryver.dev

Why AI coding agents need runtime context

A coding agent is as good as the context you provide it. With Aspire MCP, you can give your AI coding agents context from your running system, enabling them to make better, well-informed suggestions.

Source code does not tell the whole story

Modern applications are no longer simple, isolated systems. They are composed of APIs, databases, message brokers, background workers, caches, containers, and external services. Understanding how all these pieces interact can be harder than writing the code itself.

While OpenTelemetry, Aspire, and AI agents are still relatively new and are still evolving quickly, they are becoming important tools in modern software development. When I'm working on projects, I can't imagine working without them anymore. Individually, they are already powerful tools, and together they reinforce each other.

The runtime context stack

OpenTelemetry gives you the signals

OpenTelemetry provides the foundation for observability. It captures structured logs, distributed traces, and metrics, making it possible to understand what happens inside a system at runtime. Instead of guessing why a request is slow or why a service fails, OpenTelemetry gives developers the data needed to investigate the real behavior of the system.

Aspire: application model and local orchestration

Aspire orchestrates your distributed environment and gives you a structured way to model the different parts of your system using code. With Aspire, we get an isolated local development environment, with OpenTelemetry integrated from the start and support for building and deploying the application model. Logs, traces, and resource statuses are all centralized in one place, and are easily accessible in the Aspire dashboard.

AI agents: better context means better suggestions

AI agents add another layer on top of this. While agents already help us write, understand, and maintain code and documentation, they can do much more when they have access to the right context (information). Instead of just looking at the source code, they can also inspect the runtime behavior of the system and make more informed suggestions. This is where OpenTelemetry and Aspire come in. They already have the context that AI agents need to understand the behavior of the system, resulting in more useful assistance.

What becomes possible

This means that instead of manually investigating logs, traces, and metrics to understand the behavior of the system, or manually debugging the application, you can ask your AI agent to do it for you.

When these three tools work together, you can ask your AI agent to analyze the runtime behavior of your system, and to provide insights and suggestions based on that. The results are more accurate and useful than if it only had access to the source code.

This is useful in different scenarios, for example:

• analyze logs to find the source of an error
• identify the root cause of a performance issue
• pinpoint the source of a failure in a distributed system
• document the flow through the system
• act as a rubber duck to explain the behavior of the system

It can often go one step further: after identifying a likely issue, it can suggest and implement a fix that you can review.

Aspire MCP: connecting your agent to the running application

Aspire MCP is a local MCP server exposed by Aspire. MCP is a protocol that lets AI tools communicate with external systems in a structured way. In our case, the external system is the Aspire application model.

How to enable Aspire MCP

To install the Aspire MCP server, click on the MCP icon in the top right corner of the Aspire dashboard, and follow the instructions to install the MCP server. Once installed, you can enable it for your application.

You can also run the following command in your terminal to install the MCP server, follow the setup wizard, and optionally include skills and the Playwright CLI:

 
aspire agent init

What your agent can inspect

When the MCP server is enabled, your AI code agent can use the exposed tools, such as reading the available resources, logs, and traces, enabling it to perform better.

Because the tools are exposed through MCP, they can be used by MCP-compatible AI tools, such as GitHub Copilot, Codex, or Claude Code. There is no unified configuration format for every tool yet, so the setup differs per client. Luckily, the above init command does its best to already set up the correct integration for you based on the environment you are using. For example, if you are using GitHub Copilot, it will add the MCP server to the settings for you in Visual Studio Code.

Example

Imagine a front-end application that suddenly shows an empty screen.

The code looks fine at first sight. The page calls the API, the API calls another service, and the UI expects data back. Without runtime context, an AI coding agent can only inspect the source code and guess where the problem might be.

With Aspire MCP, the agent can inspect the running application instead. It can check the resource status, see that one downstream service is unhealthy, read the API logs, follow the trace from the front-end request through the backend, and connect the empty screen to the service that is actually failing.

This changes the investigation. Instead of asking "what in this code could be wrong?", the agent can ask "what actually happened when this request ran?".

Example prompt

An example prompt could be:

 
The front-end application shows an empty screen when I open the orders page.
Please investigate this using the Aspire MCP tools before suggesting a fix.

Or a longer version of the prompt to be more specific about the investigation:

 
The front-end application shows an empty screen when I open the orders page.
Please investigate this using the Aspire MCP tools before suggesting a fix.
Include the following checklist to structure your investigation:
Check:
the status of the Aspire resources
the logs for the front-end, API, and downstream services
the trace for the failing request
any unhealthy or unavailable dependencies
I want you to determine:
which request from the front-end is failing
whether the API receives the request
which downstream service is involved
whether that service is unhealthy, unavailable, or returning an error
the most likely root cause based on the runtime data
the safest fix or next step

Conclusion

OpenTelemetry provides the raw runtime logs, traces, and metrics. Aspire organizes those signals and connects them to the application model. AI agents can use that structured context to help debug issues, explain failures, identify performance problems, and suggest improvements.

That changes how we use coding agents, with the result of a significantly enhanced development experience.

Instead of manually collecting logs, copying trace output, and explaining the current state of the system in a prompt, you can ask the agent to inspect the running application directly.

The AI agent quality also sees improvements. It doesn't guess anymore, the agent uses the runtime context to analyze the system's behavior, resulting in more reliable insights and suggestions.

This allows us to spend less time on manual investigation, and more time on building reliable software that creates value.

Read Keep Agentic AI Simple: A Practical Workflow for Software Development on timdeschryver.dev

Over the past year, I changed my perspective on AI in software development. I used to be skeptical, but after watching Burke Holland's content on Copilot agents, I realized that I had to give it another try. From using AI as a simple code completion tool, to a tool to generate tests or simple isolated enhancements and smaller tasks, I started to see it as a system that's capable of doing much more. Fast forward to today, I'm using it more and more to create new features from scratch.

Over the last month I used Agentic AI to rewrite a project entirely from scratch, and the results are amazing. The speed boost is incredible, and the quality of the code is good, not perfect, but good enough in my opinion. In this blog post, I want to share my experience and thoughts on AI in software development, and why I think it's a game-changer for software development.

No, I didn't vibe code the project, because while it's could be faster, I think this practice causes issues in the long term. Instead - and because we're currently in the classic cycling season I want to use a cycling metaphor -, I would say that I'm seeing AI as a (super-)domestique, while I'm the team leader.

In road bicycle racing, a domestique is a rider who works for the benefit of their team and leader, rather than trying to win the race. In French, domestique translates as "servant". The use of the term dates back to 1911, although such riders had existed before then.

This allowed me to focus on the high-level design and architecture of the project, while I let the AI handle the implementation details and most of the work. In the end, you're still the leader who needs to cross first over the finish line, just as Wout van Aert won Paris Roubaix to raise the cobblestone. A leader who thinks about the strategy, and can communicate this clearly to his team. Just as pulling in an external dependency, we're still responsible for the overall direction and quality of the project, but we can leverage the power of AI to get there faster and more efficiently.

Overall architecture and design

The project I worked on, uses an ASP.NET API as the backend and an Angular frontend, orchestrated by Aspire.

Before letting the agents loose, I've set up the project structure the way I wanted.

I used the same design as mentioned in Treat your .NET Minimal API Endpoint as the application layer using a Vertical Slice architecture. I prefer the slices approach because it separates the different uses cases of an application, which to my feeling helps the agent as well (and makes it easier to rewrite or delete code when requirements changes). For Angular, I decided to use all the Signal API features, and no external UI library. After the initial setup, I let the AI handle the implementation of the features.

The goal of this project was to act as a sandbox to experiment with different approaches and techniques, to get myself familiar with the capabilities and limitations of AI in software development. Disclaimer: I'm certainly not an AI-expert, but I wanted to share my successful experience, and I hope it can inspire you to explore AI. I also want to share some of the techniques and approaches I used, and how these helped me to get the most out of AI in software development.

AGENTS.md

If you're already familiar with AI Agents, then the AGENTS.md file shouldn't be new to you. This file is always included in the Agent's context, and it contains the instructions that the agent follows while working on the project. Because it's included for every request it's a good practice to add the general guidelines, the structure of the project, and commands the agent can use in this document. Different tools might have their own version of this file, e.g. in GitHub Copilot it's called instructions.md, or claude uses CLAUDE.md, but the idea remains the same across the tools.

Instead of different versions of this file, using the AGENTS.md naming is a standard, and is supported in most of the tools. However, CLAUDE code does not support this file, but it's possible to create a symlink or reference the AGENTS.md file using @AGENTS.md. This makes it easy to switch between tools, without having to change the instructions for the agent.

You don't have to write the AGENTS.md file manually, you can also just let the agent generate it for you. In my case this file contains the technology stack, the commands to use (build, test, lint, etc.), the coding style and conventions, and the overall flow of the application. This way, the agent has a clear understanding of the project and its requirements, and uses this to generate code that is aligned with the overall direction of the project.

I also found that adding a database diagram in the mermaid syntax to the AGENTS.md file, is a great way to give the agent a better understanding of the data model of the project. In bigger application this big diagram won't be readable for humans, but it does help the agent to understand the application's model to pinpoint where it needs to be.

Because this file is critical to have good results, it's a good idea to review your AGENTS.MD file regularly to keep it up to date, to ensure that the instructions and guidelines are still relevant and accurate. This way, you can be confident that the agent is always working with the latest information, and that it can generate code that is aligned with the overall direction of the project.

To keep the file in a good shape, ask the agent to update the AGENTS.md after introducing a new concept (within the same session). I also added recurring mistakes to this file to improve the quality of the agent.

Skills

I do use Agent Skills to extend the capabilities of the coding agent. Skills are just markdown files (it can also contain scripts) to teach your agent specific knowledge about tools and technology, or team rules that the agent needs to follow in certain situations. The agent can access these skills, and automatically pulls in the skill(s) when it detects it could be useful for a given task. For example, when I ask the agent to create a new Angular component, it loads the Angular skill, and uses it to generate the component code.

The main differentiation between skills and AGENTS.md, is that the agent file is always included in the context, while skills are only included when they are relevent. This is important to keep the context window manageable, in order to get the best results.

Another usage of a skill is that it's possible to invoke the skill on demand using a slash command. In this case the skills feature is the successor of slash commands or file instructions, and provides a standardized way to invoke repetitive tasks.

Many tools add the skills to the ./agents/skills folder, however CLAUDE uses ./claude/skills. As a workaround you can create symlinks to cover both causes without duplicating the skills.

Skills can also be picked up by different agents, this makes it easy to centralise and share the knowledge between different agents.

There are plenty of good skills available. To search for skills, I recommend using https://skills.sh. To install a skill in your project, you can use the following command. After the installation the skill is added to your project repository (or on your system), so it can be re-used by your team.

 
npx skills add dotnet/skills

I used skills to teach the agent the latest Angular features, using the official Angular skill, and I also used several official .NET skills to provide the agent the best practices (e.g. to write good and performant Entity Framework code). Besides the technical skills, I also installed the pnpm, NuGet, Aspire, and several documentation skills (e.g. to create mermaid diagram) to let the agent handle the project management and documentation tasks.

Using the skill-creator skill, it's also possible to generate your own skills, or you can also write them manually if you prefer. However using the creator skill will also include the best practices to write the skill. I recommend creating custom skill for your team-level rules, or for areas where an agent usually goes off the track.

For my project, a must-have, was creating a design skill containing direction and feeling of the application. This skill documents the overall/brand style (colours, fonts, etc.), and the available components within the project. Without this skill, I experienced that the agent would often deviate from the general design, leading to inconsistent design elements and a bad user experience. By using the design system skill, the agent was able to generate consistent and high-quality UI code, which was aligned with the overall design direction of the project. This was especially required for the codex models, and less for the claude models.

Because most of my endpoints are implemented in the same way, I also used the existing endpoints as examples to let the agent generate an "endpoint template" skill. This made additional generated endpoints consistent with the existing ones.

Agent skills are a great way to improve the overall quality, from anything coding related to general tasks such as writing and updating the documentation.

That's also the reason why I'm not using MCP servers. While these were heavily promoted a couple of months ago, these bloat the context window of the agents, resulting in lower quality output. There are many skills and/or CLI tools (which skills can use) that can replace tasks for an MCP server, for example for Playwright CLI, GitHub CLI, and many more. I've only configured the Aspire MCP, and for a brief moment a Figma and Google Stitch to try out design integrations but this wasn't a great success.

Spec-driven development

While the prompt was important (see prompt-engineering), models are becoming better to interpret our requests. This is good news for me, because prompting was never my forte. To write the specifications for new features, I used spec-driven development using OpenSpec. I prompted what I wanted to achieve in a few sentences, and OpenSpec generated 3 files for me:

• a proposal.md file, where the functional analysis of the feature is described, within a few sections, a summary, a "what", a why, the scope and not in scope, and a list of success criteria.
• a design.md file, where the technical design of the feature is described, including the areas, API endpoints, Angular components, and models that need to be created or changed, and the implementation details.
• a tasks.md file, where the step-by-step implementation plan is described, with a list of tasks that need to be done to implement the feature, and the order in which they should be done.

When I was unhappy with the generated documents, I could easily change them using a second or third prompt, or make manual changes to the generated files.

I found it to be a great way to communicate the requirements and expectations to the coding agent, and it helped me to get a better understanding of the feature, the implementation, and possible caveats and drawbacks. It also helped me to keep track of the progress, and to steer that the feature is implemented according to the requirements and expectations. If you want, you can change the files OpenSpec generates, but I found that the default templates are good enough for me. An additional benefit of using OpenSpec, is that these (archived) documents are a part of the codebase, and are committed with the rest of the code.

To make smaller changes and bugfixes to existing features, I used a more traditional approach, where I just prompted the agent to make the changes directly, or to create a plan suggestion. This approach worked well without the need for a more formal spec, but I found that for larger features, the spec-driven approach was more effective and efficient. Otherwise, I found that the agent would often miss some subtle details, or that it would implement the feature in a way that was not aligned with my expectations. This meant I had to do multiple iterations to get the feature right, which was time-consuming.

In short, use spec-driven development for bigger features, while it's possible to skip this step for smaller changes or bugfixes.

Instead of OpenSpec, you can also use GitHub's SpecKit.

This way of working also divides the agent's context in multiple steps, again resulting in a better outcome. Another variation of spec-driven development is Research Plan Implement (RPI), which is almost the same.

Tools and models

The key to working with agents is to provide just enough context, not too little, but certainly not too much as well.

While there are a few differences in the models that I've used (Claude and Codex), I've found them to be equally useful. These models evolve at a fast pace, and I think it doesn't matter as much as it used to be. Every few months a new and better model is released, so even if one model is currently better, it can shift in the other direction before you know it. That being said, the only difference that I've experienced, is that Claude is better in design tasks.

So far, I haven't used custom agents, mostly because I have a feeling that this will pull me into a rabbit hole, while I'm pleased with the default coding agent in combination with skills.

The tools we use to interact with the models are an abstraction layer around the models, which is called the harness. If I'm well informed, this layer is becoming thinner because the power of AI lies within the models themselves. Because of this, there isn't much difference between the tools, and they are becoming more and more identical.

This is also something that I've experienced while trying out different tools, from GitHub Copilot, to Codex and Claude, to OpenCode. The one harness is more independent then another, but this is just a matter of preference (and configuration). Because the fast pace of AI, I do like and prefer OpenCode because it provides the option to use different models while remaining in the same tool. This is similar to or GitHub Copilot, but additionally it prevents a vendor lock-in as you can connect to different providers.

Workflow

Using agents has drastically changed my workflow.

Instead of writing code, and writing code, and writing code. I now delegate this task to the coding agent, while I can give more attention to more critical aspects in the process.

I usually start with using the OpenSpec propose skill to generate a plan to implement. When the plan is in a good shape, I ask the coding agent to implement the steps within the plan. After the feature is complete I test the code from a functional standpoint, and I review the critical code paths in depth. To make quick progress I'm not interested in the implementation details. For example, I decided to use custom UI components instead of using a component library. I treated this code as an external dependency, similar to a third-party package, and I only look at the public API, not the internals of the components. This usually takes a few iterations, and after going back and forth, when I'm happy with the results I'm using the git and GitHub skills to commit the changes and open a pull request.

When the agent is busy with generating a plan or implementing the plan, I usually do one of the following: review (with or without an agent) code, start generating a new plan, updating the documentation (also using an agent), refactor code, or getting a coffee. While it worked on a big task, it can also happen that I'm going for a quick run while the agent is working.

Team structure and ceremonies

For this project, I was the sole developer, so I didn't have to worry about team structure and ceremonies. However, I'm sure that communication and collaboration is more crucial than ever.

I have the feeling that what I was used to deliver in two-week sprints, is now shipped within a couple of days or even less. Therefore, having frequent check-ins and review moments, are critical to keep everyone aligned. Instead of coding for days/weeks and then having a big review at the end, it's better to have more frequent reviews. This to catch potential issues or misalignments early on, and to ensure that the project is on the right track.

That's why I also believe that the role of a Product Owner and/or Project Manager will become more important. The issue isn't that there isn't enough time and resources anymore, but that there will be an overflow of non-important features. The skill will be to focus on the areas that provide business value, and to not be tricked into all the bells and whistles that provide no-value and are quick to deliver.

I won't be surprised that pair programming could have a new meaning. Instead of having two developers working on a feature, why not having a developer and a stakeholder or key-user working on a feature together. Atleast, this is something that I'm looking forward to try out.

Conclusion

We can't ignore that our industry is changing. To stay relevant it's important to embrace this change early on.

As Dan Clarke wrote in Developers are System Thinkers, not Code Monkeys: Don't be the developer who's afraid of AI. Be the developer who treats it as the latest system to learn. Play with it. Experiment. Build things with it. The more you understand how it works, the better you'll be at leveraging it - and that's exactly what we've always done.

Because introducing AI can be overwhelming at first, atleast it was for me, I think it's a good idea to start simple and to not bring in all of features at once. The tools and techniques are also changing in a rapid pace, so it's a challenge to keep up with best practices, especially if it's not your main focus area. Using standardized tools and practices helps to keep everything manageable. While choosing tools, I also think it's important to think about a potential vendor lock-in.

By only using the default AI coding agent you already see some positive results, but this probably won't impress you, nor be consistent in their output. My recommendation is to start with the bare minimum, and include the files we discusses when they are required. This can be done when you notice that the agent keeps making the same mistakes.

I was impressed with the overall quality improvement with introducing the AGENTS.MD file, and even more so by adding Agent Skills to the project. This resulted in major speed improvements by using AI in my development workflow. To prevent countless back-and-forth's between me and the model, a good specification with clear requirements helps to boost the productivity.

To include these instructions across different tools you can use symbolic links to prevent the duplication, and the hassle to keep the files in sync. I prefer to keep the original files tools-agnostic and to stay close to standard, as a workaround create symlinks pointing to these locations to support the tools who defer from the standard. This practice makes it easier to try out new tools, or eventually switch between tools.

Because AI is evolving in a fast pace this setup needs to be continuously re-evaluated, and keep re-iterating to see what works best for you and your setup.

While this all sounds good, keep in mind that AI is not the silver bullet. AI can help you ship faster, but only if you stay in the driver's seat. Just as within software teams now, there will always be areas that could be (or are required to be) polished up.

I'm seeing our role as software engineer becoming less technical detailed, instead our role is to provide good guardrails to let the agent do its job (and this might also become less important over the next months and years?), while still taking ownership over the product that we're building. That's why it's a good idea to start your AI journey sooner than later.

Instead of focusing on delivering code, I can now give more focus to delivering value, which was - and still is - the most important and brings me the most joy.

Read Containerize an ASP.NET Core BFF and Angular frontend using Aspire on timdeschryver.dev

In this article, we use the bff-aspnetcore-angular template from Damien Bowden as a starting point, and integrate Aspire into the project to improve the local development experience and prepare it for containerized deployment.

The template implements a BFF (Backend For Frontend) architecture. As Damien has said it in his article "The project implements a secure web application using Angular and ASP.NET Core. The web application implements the backend for frontend security architecture (BFF) and deploys both technical stack distributions as one web application. HTTP only secure cookies are used to persist the session. Microsoft Entra ID is used as the identity provider and the token issuer.". Other security features include the use of CSP (Content Security Policy) headers and Anti-Forgery tokens.

The template and the related articles are already a great starting point for building a secure web application using ASP.NET Core and Angular. We recently used it to create a new project, and integrating Aspire improved the development experience. It also gave us a straightforward way to package the application for deployment with Docker.

If you have not looked at the template and the related articles yet, the project consists of an Angular application and an ASP.NET application. The Angular application is served from the ASP.NET application, and the ASP.NET application acts as a BFF for the Angular application by handling authentication and API requests. While running locally, the ASP.NET application proxies requests to the Angular development server. In production, the Angular application is served as static files from the wwwroot folder of the ASP.NET application.

Let's go through the steps. If you're just interested in containerizing the application, you can directly jump to the Dockerize the project section.

Integrate Aspire into the project

I followed the same approach described in my A minimal way to integrate Aspire into your existing project article.

Within the existing solution, create a new Aspire AppHost project, which will be used to run both the ASP.NET Server project and the Angular project. Then, configure the AppHost to serve the ASP.NET Server project and the Angular project.

To serve the Angular project, we can use the AddJavaScriptApp method from the Aspire.Hosting.JavaScript packages, which first needs to be installed in the AppHost project.

 
dotnet add package Aspire.Hosting.JavaScript

Then, we can configure the AppHost to serve the ASP.NET and the Angular project by adding the following code to the AppHost.cs file.

 AppHost/AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
var ui = builder
    .AddJavaScriptApp("bff-angular", "../ui", runScriptName: "start")
    // Automatically install npm packages when the application is run
    .WithNpm(installCommand: "install", installArgs: ["--force"])
    // Pass the PORT environment variable to the Angular application
    // Which is used by the Angular development server to determine the port to run on
    .WithHttpEndpoint(env: "PORT");
 
var server = builder.AddProject<Projects.BffMicrosoftEntraID_Server>("bff-server");

Because the Angular project is served from the ASP.NET application, we need to configure the relationship between the two projects. We can do this by adding a reference to the Angular project in the ASP.NET project and configuring the ASP.NET project to serve the Angular application as static files.

 AppHost/AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
var ui = builder
    .AddJavaScriptApp("bff-angular", "../ui", runScriptName: "start")
    .WithNpm(installCommand: "install", installArgs: ["--force"])
    .WithHttpEndpoint(env: "PORT");
 
var server = builder.AddProject<Projects.BffMicrosoftEntraID_Server>("bff-server")
    .WithReference(ui)
    .WaitFor(ui)
    .WithChildRelationship(ui);

Creating this relation between the two projects and create an services__bff-angular__http__0 environment variable that contains the URL of the Angular application, which can be used in the ASP.NET application to configure the static file serving. In the current version this URL is hardcoded.

ServiceDefaults

You can also create a new ServiceDefaults project to configure the standard middleware for all services in one place, for example, to add OpenTelemetry support. After creating the project, add a reference to the ServiceDefaults project in the Server project and call the AddServiceDefaults method in the Program.cs file to apply the default configuration to the server project.

 Server/Program.cs 
var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();

Server changes

To reroute the Angular routes to the Angular development server, the template uses YARP (Yet Another Reverse Proxy). To know the URL of the Angular development server, the template uses a hardcoded URL in the appsettings.Development.config file. This is not ideal, as it can lead to issues when running the project in different environments. By using the environment variable created by the AppHost, we can make the configuration more flexible and avoid hardcoding URLs. The bff-angular is the name of the Angular project given in the AppHost.cs file.

 "appsettings.Development.config" 
{
  "UiDevServerUrl": "https://localhost:4201",
  "ReverseProxy": {
    "Routes": {
        ...
    },
    "Clusters": {
      "cluster1": {
        "HttpClient": {
          "SslProtocols": ["Tls12"]
        },
        "Destinations": {
          "cluster1/destination1": {
            "Address": "https://localhost:4201/"
            "Address": "https+http://bff-angular"
          }
        }
      }
    }
}

This doesn't work out of the box, because YARP can't resolve the bff-angular URL. To make it work, we need to configure YARP to use the environment variable created by the AppHost for the Angular development server URL. This can be done by installing the Microsoft.Extensions.ServiceDiscovery.Yarp package in the Server project and configuring YARP to use the environment variable for the Angular development server URL.

 
dotnet add package Microsoft.Extensions.ServiceDiscovery.Yarp

After the installation, configure YARP to discover destinations using the AddServiceDiscoveryDestinationResolver() extension method.

 Server/Program.cs 
var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();
 
...
 
var services = builder.Services;
services.AddReverseProxy()
        .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"))
        .AddServiceDiscoveryDestinationResolver();

To render the Angular application, also update the _Host.cshtml file to load the index.html file from the Angular development server in development. Again, this uses the environment variable instead of the UiDevServerUrl configuration value that was previously hard coded.

 server/Pages/_Host.cshtml 
@page "/"
@namespace BlazorBffAzureAD.Pages
@using System.Net;
@using NetEscapades.AspNetCore.SecurityHeaders;
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, NetEscapades.AspNetCore.SecurityHeaders.TagHelpers
@inject IHostEnvironment hostEnvironment
@inject IConfiguration config
@inject Microsoft.AspNetCore.Antiforgery.IAntiforgery antiForgery
@{
    Layout = null;
 
    var source = "";
    if (hostEnvironment.IsDevelopment())
    {
        var httpClient = new HttpClient();
        source = await httpClient.GetStringAsync($"{config["BFF_ANGULAR_HTTPS"] ?? config["BFF_ANGULAR_HTTP"]}/index.html");
    }
    else
    {
        source = System.IO.File.ReadAllText($"{System.IO.Directory.GetCurrentDirectory()}{@"/wwwroot/index.html"}");
    }
 
    var nonce = HttpContext.GetNonce();
 
    // The nonce is passed to the client through the HTML to avoid sync issues between tabs
    source = source.Replace("**PLACEHOLDER_NONCE_SERVER**", nonce);
 
    if (hostEnvironment.IsDevelopment())
    {
        // do nothing in development, Angular > 18.1.0 adds the nonce automatically
        var viteScriptToUpdate = """<script type="module" src="/@vite/client"></script>""";
        source = source.Replace(viteScriptToUpdate, $"""<script type="module" src="/@vite/client" nonce="{nonce}"></script>""");
    }
 
    // link rel="stylesheet"
    var nonceLinkStyle = $"<link nonce=\"{nonce}\" rel=\"stylesheet";
    source = source.Replace("<link rel=\"stylesheet", nonceLinkStyle);
 
    // link rel="modulepreload"
    var nonceLinkModulePreload = $"<link nonce=\"{nonce}\" rel=\"modulepreload";
    source = source.Replace("<link rel=\"modulepreload", nonceLinkModulePreload);
 
    var xsrf = antiForgery.GetAndStoreTokens(HttpContext);
    var requestToken = xsrf.RequestToken;
 
    // The XSRF-Tokens are passed to the client through cookies, since we always want the most up-to-date cookies across all tabs
    Response.Cookies.Append("XSRF-RequestToken", requestToken ?? "", new CookieOptions() { HttpOnly = false, IsEssential = true, Secure = true, SameSite = SameSiteMode.Strict });
}
 
@Html.Raw(source)

Angular changes

In the original template, the Angular application was built into the wwwroot folder so it's automatically included when the ASP.NET application is deployed. Because this isn't the default behavior when building an Angular application and it's also not very visible (added to the angular.json configuration), I prefer to use Aspire's infrastructure.

Therefore I removed the output path configuration from the angular.json file. Now when the application is built, it reverts back to the default behavior to add the output build into the dist folder of the Angular project.

 angular.json 
{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "ui": {
      "projectType": "application",
      "schematics": {},
      "root": "",
      "sourceRoot": "src",
      "prefix": "app",
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "outputPath": {
              "base": "../server/wwwroot",
              "browser": ""
            },
            "browser": "src/main.ts",
            "polyfills": [
              "zone.js",
              "@angular/localize/init"
            ],
            "tsConfig": "tsconfig.app.json",
            "assets": [
              {
                "glob": "**/*",
                "input": "public"
              }
            ],
            "styles": [
              "node_modules/bootstrap/dist/css/bootstrap.min.css",
              "src/styles.css"
            ]
          },
        }
    }
  }
}

Dockerize the project

So far, all these changes improve the development experience, but they also make it easy to containerize the application with Docker. By using Aspire's infrastructure, we can build and run the application without having to manually wire the configuration of the individual projects.

First, we need to add the Aspire.Hosting.Docker package to the AppHost project, which adds the container publishing capabilities we need.

 
dotnet add package Aspire.Hosting.Docker

Next, replace the AppHost contents with the following code, which configures the application for container publishing.

 AppHost/AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
var compose = builder.AddDockerComposeEnvironment("compose")
    .WithDashboard(false);
 
var ui = builder
    .AddJavaScriptApp("bff-angular", "../ui", runScriptName: "start")
    .WithNpm(installCommand: "install", installArgs: ["--force"])
    .WithHttpEndpoint(env: "PORT")
    .WithAnnotation(new ContainerFilesSourceAnnotation() { SourcePath = "/app/dist/ui/browser" });
 
var server = builder.AddProject<Projects.BffMicrosoftEntraID_Server>("bff-server")
    .WithExternalHttpEndpoints()
    .PublishWithContainerFiles(ui, "./wwwroot")
    .PublishAsDockerComposeService((_, _) => { });
 
// In publish mode the Angular app is embedded in the server Docker image.
// The dev-time frontend process is only needed when running locally.
if (!builder.ExecutionContext.IsPublishMode)
{
    server
      .WithReference(ui)
      .WaitFor(ui)
      .WithChildRelationship(ui);
}
 
builder.Build().Run();

Here we see some new concepts, let's go through them:

The AddDockerComposeEnvironment method creates a new Docker Compose setup that can run multiple services together. When the image is built, we do not want to include the Aspire Dashboard, so we disable it with the WithDashboard(false) method.

For the Angular project, we add a ContainerFilesSourceAnnotation, which tells Aspire where to find the Angular build output as a source for published container files.

For the ASP.NET project, we use the PublishWithContainerFiles method to include output of the Angular application within the ASP.NET application's image. This copies the content (the dist folder) from the Angular application to the wwwroot folder during publishing.

The WithExternalHttpEndpoints method configures the container to expose the HTTP endpoints of the ASP.NET application outside the container. Because the Angular application is served from the ASP.NET application, its content is also exposed through the same HTTP endpoint. If we don't do this, the ASP.NET application will be running in the container, but we won't be able to access it from outside the container.

Finally, we use the PublishAsDockerComposeService method to add this project as a service in the Docker Compose setup. This allows us to run the application with Docker Compose.

Resulting in the following docker-compose.yaml file being generated after running aspire publish:

 docker-compose.yaml 
services:
  bff-server:
    image: '${BFF_SERVER_IMAGE}'
    environment:
      OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: 'in_memory'
      ASPNETCORE_FORWARDEDHEADERS_ENABLED: 'true'
      HTTP_PORTS: '${BFF_SERVER_PORT}'
    ports:
      - '${BFF_SERVER_PORT}'
    networks:
      - 'aspire'
networks:
  aspire:
    driver: 'bridge'

The publish commands also generated the .env file containing the variables used in the docker-compose.yaml file, in this case, the BFF_SERVER_IMAGE and BFF_SERVER_PORT variables.

 .env 
# Container image name for bff-server
BFF_SERVER_IMAGE=
 
# Default container port for bff-server
BFF_SERVER_PORT=

Note that we don't we only create a reference between the Angular and ASP.NET project in development, but not in publish mode. This is because in publish mode, the Angular application is built and included in the ASP.NET application's image. This is required, otherwise you will receive an error during publishing that the Angular project can't be found, because it's not included in the publish context. Howerver, at the time of writing this post it does seem that this issue is resolved in the latest version of Aspire (13.2.1), so you might be able to include the reference in publish mode as well.

Next steps

If you want to customize the Docker image further, you can set image tags, set up a container registry, and integrate it with GitHub Actions for automated builds and deployments.

Conclusion

By integrating the template with Aspire first, we improve the local development experience without changing the core BFF architecture. Service discovery removes hardcoded frontend URLs, and the same setup makes it much easier to package the application for Docker-based deployment. The result is a cleaner development workflow today and a more predictable path to containerized hosting tomorrow.

Using the best practices already set out by Damien's template, this gives us a solid foundation for building secure web applications with ASP.NET Core and Angular, while also leveraging Aspire's capabilities for orchestration and containerization.

You can find the full project on GitHub, or inspect the commit that turns Damien's original template into an Aspire project with Docker support.

Read Introducing Angular Testing Library Zoneless on timdeschryver.dev

Angular Testing Library now introduces a new zoneless subpackage, a trimmed-down version of the original Angular Testing Library. This is avalable from version 19.2.1 onwards.

Why

The reason for the new @testing-library/angular/zoneless subpackage is that, over time, Angular's testing capabilities have improved, and some of the features provided by the original Angular Testing Library have become less necessary. It focuses on a more streamlined API that leverages Angular's built-in testing features.

Disabled Automatic Change Detection

The biggest change is that Testing Library's API is no longer monkey patched, such as for user events and the waitFor and findBy methods, to invoke Angular's change detection using detectChanges. This is something you won't notice by looking at the API, but it's a major internal change. This change is necessary to more closely reflect how the component behaves under real circumstances. It shouldn't have a big impact on existing test cases.

Compact API Surface

This subpackage also includes breaking changes compared with what you're currently used to. We think these breaking changes have a positive effect during rendering. For example, the componentProperties, componentInputs, componentOutputs, and inputs options have been removed in favor of a single bindings option that makes use of binding syntax to test input, output, and model bindings. Previously, there were subtle differences, which made it unclear when to use one over the other.

 example.spec.ts 
import { render, screen } from '@testing-library/angular/zoneless';
import userEvent from '@testing-library/user-event';
 
test('renders and interacts with a component', async () => {
  const user = userEvent.setup();
  await render(CustomerDetails, {
    bindings: [inputBinding('customerName', 'Alice')],
    // You can still configure providers
    providers: [],
  });
 
  const loadButton = screen.getByRole('button', { name: /load customer/i });
  await user.click(loadButton);
 
  expect(screen.getByText('Hello Alice')).toBeInTheDocument();
});

configureTestBed for more control

To make the library less dependent on Angular's APIs, some configuration options that were rarely used have been removed. Instead, it's now possible to manually configure the testing environment using Angular's TestBed API, which provides more flexibility and control over your specific testing setup.

To configure the TestBed, use the configureTestBed method. For example, you can configure the router or defer behavior.

 example.spec.ts 
import { render, screen } from '@testing-library/angular/zoneless';
import userEvent from '@testing-library/user-event';
 
test('renders and interacts with a component', async () => {
  const user = userEvent.setup();
  await render(CustomerDetails, {
    configureTestBed: (testBed) => {
      testBed.configureTestingModule({
        deferBlockBehavior: DeferBlockBehavior.Manual,
      });
    },
  });
});

Vitest Compatibility

A nice side effect of the zoneless subpackage is that it's better compatible with Vitest (browser mode).

Future Improvements

Of course, we will re-evaluate the API in the future and add more features if needed. For now, the zoneless package provides the bare minimum needed to test components, while offering a more focused and efficient testing experience for Angular developers.

Call to Action

The zoneless subpackage is available as a separate package, so you can choose to use it without affecting your existing tests. We encourage you to try it out and share your feedback. Feel free to open issues or contribute to the project if you have suggestions for improvements or new features. Your feedback helps shape the future of Angular Testing Library.

Read Angular Signal Forms Keeps Improving (v21.2) on timdeschryver.dev

In the previous blog post "Refactoring a form to a Signal Form", we refactored an existing Angular form to use the new Signal Forms feature. At the time, Signal Forms were still experimental, and we mentioned that there were some limitations and areas for improvement.

Since then, the Angular team has continued to improve Signal Forms. In this blog post, we will take a look at some of the improvements that were added in recent versions of Signal Forms (at the time of writing v21.2), including application-wide CSS classes, programmatic focus management, and a more structured submission flow.

provideSignalFormsConfig

To start with, there's a new method provideSignalFormsConfig to configure the Signal Forms in an application.

Currently, this method allows us to set CSS classes through the classes option, which are applied to form controls based on their state. This can be used to easily apply consistent styling across form controls, e.g. to re-apply the ng-* classes that were present in the previous version of Angular forms.

The classes option accepts an object where the keys are the CSS class names and the values are functions that receive the FormField to determine when to apply the class based on the form control's state. Of course, this is not limited to re-applying the ng-* classes. You can define any custom classes that you want to apply based on the form control's state.

 "app.config.ts" 
import { ApplicationConfig } from '@angular/core';
import { provideSignalFormsConfig } from '@angular/forms/signals';
 
export const appConfig: ApplicationConfig = {
  providers: [
    provideSignalFormsConfig({
      classes: {
        'ng-dirty': ({ state }) => state.dirty(),
        'ng-touched': ({ state }) => state.touched(),
        'ng-valid': ({ state }) => state.valid(),
        'ng-invalid': ({ state }) => state.invalid(),
        'custom-class': ({ state }) => state.touched() && state.invalid()
        ...
      },
    }),
  ],
};

NG_STATUS_CLASSES

If you want to re-apply all the ng-* classes, Angular provides a predefined set of classes called NG_STATUS_CLASSES that you can use with provideSignalFormsConfig to have the same behavior as the previous version of Angular forms. This is a great option for those who want to migrate to Signal Forms without losing the styling.

 "app.config.ts" 
import { ApplicationConfig } from '@angular/core';
import { provideSignalFormsConfig } from '@angular/forms/signals';
import { NG_STATUS_CLASSES } from '@angular/forms/signals/compat';
 
export const appConfig: ApplicationConfig = {
  providers: [
    provideSignalFormsConfig({
      classes: NG_STATUS_CLASSES,
    }),
  ],
};

focusBoundControl

Another improvement is the addition of the focusBoundControl method on the FormField instance.

With focusBoundControl, we can programmatically focus the first form control (based on the DOM order) within a field tree. This only works when the form control is already rendered in the DOM. If there are no elements to be focused, the method does nothing.

 
this.form().focusBoundControl();

We use this method to focus the first form control when a dialog is opened.

It also opens up new possibilities for improving the user experience, especially when it comes to form validation. For example, we can use this method to focus the first invalid form control.

To do that, we can use the errorSummary on the form instance to get a summary of all the errors in the form. Then, we can call focusBoundControl on the first field tree to focus the first invalid form control.

 
form().errorSummary()[0]?.fieldTree().focusBoundControl();

Please keep in mind that focusing an input automatically can cause accessibility issues, so ensure it enhances the user experience rather than detracting from it.

Submission API

The third improvement that we will discuss in this blog post is the new Submission API. The Submission API provides a more structured way to handle form submissions, including both valid and invalid form states.

You can implement an asynchronous submission action using the submission option in the form function. The submission option accepts an object with an action property that is called when a valid form is submitted.

The action receives the form instance as an argument, which you can use to access the form value and perform any necessary operations, such as making an API call to submit the form data. This action marks all the fields in the form as touched, so you don't have to worry about that in your implementation. The action returns a TreeValidationResult, which can be used to set validation errors on the form based on the response from the server.

 
form(
  signal<FormSchema>({...}),
  (path) => {
    // Validation comes here
  },
  // 👇 New submission API
  {
    submission: {
      action: async (form) => {
        const formValue = form().value();
 
        try {
          await service.submit(formValue);
          form().value.set({...});
          form().reset();
          return undefined;
        } catch (error) {
          return {
            kind: 'server',
            message: error instanceof HttpErrorResponse
              ? error.error.title
              : 'Something went wrong. Please try again.',
          } satisfies ValidationError.WithOptionalFieldTree;
        }
      },
    },
  },
);

The submission option also accepts an onInvalid property that is called when an invalid form is submitted. This can be used to handle any specific logic when the form is invalid. This is great in combination with the focusBoundControl method that we discussed earlier, as we can focus the first invalid form control when the form is submitted in an invalid state. onInvalid receives the form instance as an argument, and does not return anything.

 
form(
  signal<FormSchema>({...}),
  (path) => {
    // Validation comes here
  },
  // 👇 New submission API
  {
    submission: {
      action: async (form) => {
        const formValue = form().value();
 
        try {
          await service.submit(formValue);
          form().value.set({...});
          form().reset();
          return undefined;
        } catch (error) {
          return {
            kind: 'server',
            message: error instanceof HttpErrorResponse
              ? error.error.title
              : 'Something went wrong. Please try again.',
          } satisfies ValidationError.WithOptionalFieldTree;
        }
      },
      onInvalid: (form) => {
        form().errorSummary()[0]?.fieldTree().focusBoundControl();
      },
    },
  },
);

But how do we trigger the submission action? Instead of implementing a submit event handler, we now set the (new) formRoot directive on the form element to bind the form instance to the form in the template. This automatically handles the form submission (for example, when the user clicks a submit button or presses enter in an input field), and triggers the appropriate submission action based on the form's validity.

formRoot directive

The formRoot directive also adds the novalidate attribute to the form element, which disables the browser's default validation.

 "form.component.html" 
<form [formRoot]="form"></form>

The directive needs to be imported from the @angular/forms/signals package in the component's imports array.

 "form.component.ts" 
import { Component } from '@angular/core';
import { FormRoot } from '@angular/forms/signals';
 
@Component({
  selector: 'app-form',
  imports: [FormRoot],
  templateUrl: './form.component.html',
})
export class FormComponent {
  form = form(...);
}

Conclusion

These improvements make Signal Forms feel more complete and practical to use in real applications. With provideSignalFormsConfig, focusBoundControl, the Submission API, and the formRoot directive, several rough edges from the earlier versions have already been smoothed out. Signal Forms is clearly evolving quickly, and these additions make it an even more compelling option if you want to build forms with Angular's signal-based APIs.

Read A minimal way to integrate Aspire into your existing project on timdeschryver.dev

We adopted Aspire in our (.NET 8) codebase without touching our existing architecture, and it worked.

Aspire isn't just for new projects. Existing projects can also benefit from Aspire's features. If you have an existing project and want to integrate Aspire, you don't have to go all-in from the start. In this post, we'll take a look at a minimal integration approach that lets you gradually adopt Aspire without having a big impact on the rest of your existing codebase.

Aspire has many great features, but you don't have to use all of them at once. Recently, our team started integrating Aspire into our existing project (on .NET 8) by only creating an Aspire AppHost project to run all of our projects with a single command. Doing this also allowed us to migrate from Project Tye without making significant changes to our codebase and build processes right away. This gave us a chance to understand how Aspire works and how it can improve our development process.

What "minimal" means in this post

This post focuses on the smallest useful integration:

• Add an Aspire AppHost project.
• Register existing .NET and Angular projects in the AppHost.
• Run everything from one place.

It does not yet cover service defaults, containers, secrets migration, or deployment.

Creating the AppHost project

To get started with the bare minimum, add a new project using the Aspire AppHost template to your solution.

You can do this in your IDE by right-clicking on your solution, selecting "Add" > "New Project", and then searching for "Aspire AppHost". Follow the prompts to create the project. The project will be created with an empty AppHost file that serves as the entry point for your application.

 AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
builder.Build().Run();

Alternatively, you can use the Aspire CLI to create the project with the following command. The command runs a wizard that guides you through creating a new Aspire AppHost project and asks which projects you want to include.

Sadly, the command didn't work for our project at the time of writing (I suspect this is due to our current SDK/tooling combination on .NET 8), but it's still worth trying in your environment.

 
aspire init

Adding .NET projects to the AppHost

Our project has multiple ASP.NET projects, and we wanted to run all of them with a single command. To do this, we started registering them in the AppHost file using the builder.AddProject<T>() method (you also need to add references to these projects in the AppHost project file).

 AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
var projectA = builder.AddProject<Projects.ProjectA>("project-a");
var projectB = builder.AddProject<Projects.ProjectB>("project-b");
 
builder.Build().Run();

Adding Angular projects to the AppHost

Besides our ASP.NET projects, we also have Angular projects in our solution. We wanted to run those from the same place, so we added them to the AppHost too. Before adding an Angular project to the AppHost, add the Aspire.Hosting.JavaScript package to the AppHost project.

 
dotnet add package Aspire.Hosting.JavaScript

The next step is to register the Angular project(s) in the AppHost file using the builder.AddJavaScriptApp() method.

 AppHost.cs 
var builder = DistributedApplication.CreateBuilder(args);
 
var projectA = builder.AddProject<Projects.ProjectA>("project-a");
var projectB = builder.AddProject<Projects.ProjectB>("project-b");
 
var frontend = builder.AddJavaScriptApp("frontend", "../AngularProject")
    .WithNpm(installCommand: "ci")
    .WithUrl("https://localhost:4200");
 
builder.Build().Run();

Running the AppHost

Now that we have our projects registered in the AppHost, we can run the AppHost - just as any other project - to see the results. When you run the AppHost, it will start all of the registered projects and provide you with a dashboard.

Here, we can also see that JavaScript projects include an installer resource that installs npm dependencies for those projects, so you don't have to worry about that anymore. You can opt out of this behavior by setting the install property to false in the WithNpm() method, for example: WithNpm(installCommand: "ci", install: false).

Within the dashboard, the only working feature for us right now is the application logs.

Next steps

This is just the beginning of what you can do with Aspire. With this minimal integration in place, you can start exploring more Aspire features as you become more comfortable with it, such as:

• Enabling Aspire's distributed tracing: With Aspire's distributed tracing, you can get insights into how your different projects are interacting with each other, and identify any performance bottlenecks or issues in your application. This can be done using a ServiceDefaults project and by configuring existing projects to use ServiceDefaults.
• Integrating Docker containers: To create an isolated environment for your application, it's possible to integrate Docker containers into your AppHost. This allows you to run your application in a consistent environment across different machines and platforms. For example, you can add a SQL or Redis container to your AppHost.
• Migrating to Aspire's secrets management: With Aspire's secrets management, you can securely store and manage sensitive information such as database connection strings, API keys, and other secrets. This migration will move existing secrets and appsettings to the AppHost.
• Thinking about Release management: It's also possible to use Aspire to generate artifacts to host your application. For example, you can generate a docker compose file containing the entire project (with dependencies), or you can also set up an entire environment within Azure with all the necessary resources to host your application.

Conclusion

Aspire is a great tool to orchestrate and manage your applications. In this post, we've seen that you don't have to go all-in with Aspire from the start and that you can gradually introduce it into your existing project.

My team started with a simple Aspire integration that focuses on one practical outcome: running all projects with a single command from the AppHost. For us, this was a quick and easy way to introduce Aspire.

Through the Aspire dashboard we can already access logs from all our projects in one place. There's also a MCP Server, which will become smarter and better over time, when we enable more features.

From here, we can explore additional Aspire features as we get more comfortable with it and unlock more value without refactoring our existing codebase right away.

Read Improve the quality of your Angular component snapshots with Vitest on timdeschryver.dev

To test an Angular component, I sometimes use a snapshot test to validate the DOM. This can be a quick way to verify a component with few interactions renders correctly. Snapshot testing was already possible with Jest, but if you are migrating your test suite to Vitest, you will notice a couple of differences.

In this post I want to point out a small change you can make to improve your snapshots. If you were using Jest, this improvement is also helpful because you do not have to change your existing tests.

Your first snapshot test

For a small demonstration, let's take a look at the following snapshot test, which renders the App component and verifies the fixture matches the snapshot.

 app.spec.ts 
import { render } from '@testing-library/angular/zoneless';
import { App } from './app';
 
it('creates the app', async () => {
  const { fixture } = await render(App);
  expect(fixture).toMatchSnapshot();
});

Running the above test for the first time can take a long time, and may even time out. At the end, the test should generate a snapshot, and when you look at the output, it explains why it was so slow. In this example, the snapshot contains about 803,000 lines of output, because it includes the entire component fixture. Here's a small snippet of the generated snapshot:

 __snapshots__/app.spec.ts.snap 
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`App > should create the app 1`] = `
ComponentFixture {
  "_appRef": ApplicationRef {
    "_destroyListeners": [],
    "_destroyed": false,
    "_injector": R3Injector {
      "_destroyed": false,
      "_ngOnDestroyHooks": Set {
...

As you can see, this is not very useful. To make the test valuable, we can pass the HTML element to the snapshot instead of the component fixture.

 app.spec.ts 
import { render } from '@testing-library/angular/zoneless';
import { App } from './app';
 
it('creates the app', async () => {
  const { fixture, container } = await render(App);
 
  expect(fixture.nativeElement).toMatchSnapshot();
  // or
  expect(container).toMatchSnapshot();
});

Running the tests again now results in a better snapshot. In the new snapshot you can see the DOM content of the App component. For example, we can now clearly see that the component renders 3 card components.

 __snapshots__/app.spec.ts.snap 
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html exports[`creates the app 1`] = `
<div _nghost-a-c4254472376="" id="root0" ng-version="21.1.3">
  <app-card _ngcontent-a-c4254472376="" _nghost-a-c2695974021="">
    <div _ngcontent-a-c2695974021="" class="card-shadow">
      <div _ngcontent-a-c2695974021="" class="card-divider" />
      <app-card-title _ngcontent-a-c4254472376="">
        <!--container-->
        Card Title 1
      </app-card-title>
      <div _ngcontent-a-c4254472376="">Card details</div>
    </div>
  </app-card>
  <app-card _ngcontent-a-c4254472376="" _nghost-a-c2695974021="">
    <div _ngcontent-a-c2695974021="" class="card-shadow">
      <div _ngcontent-a-c2695974021="" class="card-divider" />
      <app-card-title _ngcontent-a-c4254472376="">
        <!--container-->
        Card Title 2
      </app-card-title>
      <div _ngcontent-a-c4254472376="">Card details</div>
    </div>
  </app-card>
  <app-card _ngcontent-a-c4254472376="" _nghost-a-c2695974021="">
    <div _ngcontent-a-c2695974021="" class="card-shadow">
      <div _ngcontent-a-c2695974021="" class="card-divider" />
      <app-card-title _ngcontent-a-c4254472376="">
        <!--container-->
        Card Title 3
      </app-card-title>
      <div _ngcontent-a-c4254472376="">Card details</div>
    </div>
  </app-card>
  <!--container-->
</div>
`;

Improve the snapshot quality using snapshot serializers

While this is an improvement, and you might find this is already good enough, I think the snapshot contains too much noise. When you pay close attention (to be honest, you cannot miss it), you notice additions injected by Angular, such as _ng attributes and <!--container--> comments. These make the snapshot harder to review and the snapshot is more likely to change, for example after an Angular upgrade.

If you are already familiar with Jest snapshot testing, this extra noise should be something you do not see in Jest snapshots. This is not because of the Jest test runner, but because the jest-preset-angular library makes use of custom snapshot serializers to prettify the output. To resolve the Vitest snapshot pollution, we're also required to use custom serializers in Vitest.

To configure Vitest, first create a vitest.config.ts file in the src folder of your Angular project. Next, reference this file in angular.json as the runnerConfig option to extend (or modify) the default Angular testing behavior. With this change, the Angular test runner picks up the custom configuration to configure the Vitest test runner.

 angular.json 
{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "sandbox": {
      "test": {
        "builder": "@angular/build:unit-test",
        "options": {
          "runnerConfig": "src/vitest.config.ts"
        }
      }
    }
  }
}

Now, back to the vitest.config.ts file, where we need to set the snapshot serializer(s) used by Vitest. Luckily, it's possible to reuse the already existing serializers of jest-preset-angular.

jest-preset-angular provides 3 different serializers, each focusing on one aspect of the snapshot:

• html-comment: removes the <!--container--> comments from the snapshot
• ng-snapshot: allows you to snapshot test a component fixture instead of a DOM element (just as the very first snapshot example at the top of the page)
• no-ng-attributes: removes the _ng attributes from the snapshot

 vitest.config.ts 
import { defineConfig } from 'vitest/config';
 
// More info at https://angular.dev/guide/testing#advanced-vitest-configuration
export default defineConfig({
  test: {
    snapshotSerializers: [
      'jest-preset-angular/build/serializers/html-comment',
      'jest-preset-angular/build/serializers/ng-snapshot',
      'jest-preset-angular/build/serializers/no-ng-attributes',
    ],
  },
});

If you do not have jest-preset-angular installed, first add it using the following command:

 
npm install jest-preset-angular --save-dev

After this change, you can revert the earlier test change and simplify the test by passing the component instance to the snapshot. Behind the scenes, the ng-snapshot serializer converts the instance to the HTML structure.

 app.spec.ts 
import { render } from '@testing-library/angular/zoneless';
import { App } from './app';
 
it('creates the app', async () => {
  const {fixture} = await render(App);
  expect(fixture.nativeElement).toMatchSnapshot();
  expect(fixture).toMatchSnapshot();
});

After running the test again and approving the new snapshot, this version becomes much more compact, allowing you and your team to focus on the important output. This effect can clearly be seen in the new version of the snapshot:

 __snapshots__/app.spec.ts.snap 
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html exports[`creates the app 1`] = `
<div>
  <app-card>
    <div class="card-shadow">
      <div class="card-divider" />
      <app-card-title> Card Title 1 </app-card-title>
      <div>Card details</div>
    </div>
  </app-card>
  <app-card>
    <div class="card-shadow">
      <div class="card-divider" />
      <app-card-title> Card Title 2 </app-card-title>
      <div>Card details</div>
    </div>
  </app-card>
  <app-card>
    <div class="card-shadow">
      <div class="card-divider" />
      <app-card-title> Card Title 3 </app-card-title>
      <div>Card details</div>
    </div>
  </app-card>
</div>
`;

Analog.js

There is also a Vitest serializer in the @analogjs/vitest library, but it does not have as rich a feature set as the serializers from jest-preset-angular. The serializer provided by @analogjs is similar to ng-snapshot, which is the least interesting one in my opinion. This could change in the future (feel free to help with this GitHub issue), because for now it can feel strange to still import jest-preset-angular and this leads to conflicting peer dependencies. To start using the @analogjs serializer, take a look at the documentation.

Conclusion

Snapshot tests can be a simple way to validate component output, but the default snapshot format is noisy. By adding Angular-aware serializers, you get snapshots that are stable and easier to review. This is useful for new projects, but also especially for projects that are migrating from Jest to Vitest because the snapshot versions remain consistent.

Read Changing how ASP.NET generates OpenAPI schema names on timdeschryver.dev

By default, ASP.NET generates OpenAPI schema names based on the names of your models. However, there are scenarios where you might want to customize these names to better fit your API design. In my case, to avoid naming conflicts. In this post we'll explore how to change the way ASP.NET generates OpenAPI schema names.

Setting up OpenAPI in ASP.NET

To enable OpenAPI in your ASP.NET application, you add the OpenAPI services and middleware using the AddOpenApi and MapOpenApi methods respectively:

 Program.cs 
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();
 
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}
 
app.Run();