Forem: Anthony Simmon

Must-have resources for new .NET Aspire developers

Anthony Simmon — Mon, 27 May 2024 11:00:00 +0000

Six months after its first preview released during .NET Conf 2023, .NET Aspire becomes generally available (GA) at Microsoft Build 2024. This project, which aims to revolutionize the local development of distributed applications, has unfortunately been overlooked by some due to its preview status. This is good news for those who can now embark on the adventure. Here are some resources to learn how to use .NET Aspire.

.NET Aspire official documentation

The best place to start learning .NET Aspire is the official documentation. It includes an overview, a quickstart guide, dives into conceptual details and much more.

Official videos on the Microsoft YouTube channels

Not a fan of reading? Microsoft has published videos throughout the development of .NET Aspire. You can understand what problem it tries to solve, how the .NET team arrived at this solution, how to use it, and what the vision for the future is.

Welcome to .NET Aspire video series, a series of 9 videos released at the Microsoft Build 2024.
Building Cloud Native apps with .NET 8 | .NET Conf 2023, November 15, 2023.
ASP.NET Community Standup - .NET Aspire Update, January 23, 2024.
ASP.NET Community Standup - .NET Aspire in action, February 6, 2024.
ASP.NET Community Standup: .NET Aspire Update, April 16, 2024.
Deploy distributed .NET apps to the cloud with .NET Aspire and Azure Container Apps, April 10, 2024.

Official code samples on GitHub

The official samples repository contains valuable examples and demonstrates a small portion of the possibilities offered by .NET Aspire:

A real-world example of a distributed application with microservices,
JavaScript frontends and Node.js backends integration,
Desktop apps integration,
Various databases integration,
Dapr integration and more.

Community videos

.NET Aspire has generated a lot of enthusiasm in the community. Here are some videos from developers who have experimented with .NET Aspire and share their experiences.

What Is .NET Aspire? The Insane Future of .NET! by Nick Chapsas, November 19, 2023.
First Look at .NET Aspire - Distributed Applications in .NET 8 by Milan Jovanović, December 26, 2023.
WHY and HOW to Add .NET Aspire to ANY .NET API and Web App in Minutes by James Montemagno, April 18, 2024.
Cloud-native apps with .NET Aspire by Layla Porter, November 26, 2023.
Learn C# with CSharpFritz: Introducing .NET Aspire by Jeff Fritz, May 8, 2024.

David Fowler's experiments on GitHub

Do you want deep technical content about .NET Aspire? Watch how David Fowler pushes the limits of the .NET Aspire application model in these advanced scenarios. In my opinion, some of this content should be integrated into .NET Aspire.

My blog posts

Since the launch of .NET Aspire, I've written several articles on the subject. Here are some of my favorites:

Exploring the Microsoft Developer Control Plane at the heart of the new .NET Aspire, November 21, 2023.
.NET Aspire dashboard is the best tool to visualize your OpenTelemetry data during local development, March 25, 2024.
.NET Aspire is the best way to experiment with Dapr during local development, April 29, 2024.
Referencing external Docker containers in .NET Aspire using the new custom resources API, April 11, 2024.
Running Ruby on Rails web apps with .NET Aspire, April 18, 2024.

Social networks

If you want to stay updated with the latest news on .NET Aspire and discover what the community is building with it, I recommend following the news on X: #aspire and more recently #dotnetaspire.

You can also follow the people who work closely on .NET Aspire:

David Fowler, Distinguished Engineer at Microsoft.
Damian Edwards, Principal Architect at Microsoft.
Tim Heuer, Principal Product Manager Lead at Microsoft.
David Pine, Senior Content Developer at Microsoft.
James Newton-King, Principal Software Engineer at Microsoft.
Eric Erhardt, Principal Software Engineer at Microsoft.

.NET Aspire's source code

The .NET Aspire repository on GitHub is the source of truth for understanding how it works. I strongly encourage you to explore it in your browser or in your IDE via SourceLink.

Cover picture, from left to right: .NET Aspire documentation, David Fowler and Damian Edwards during an ASP.NET Community Standup, Aspireify.NET and Nick Chapsas on YouTube.

Disabling .NET Aspire authentication to skip the login page

Anthony Simmon — Mon, 06 May 2024 14:30:00 +0000

Preview 6 of .NET Aspire introduced a login page to access the dashboard. Unless the dashboard is launched from Visual Studio or Visual Studio Code (with the C# Dev Kit extension), the login page will appear and prompt for a token. For scenarios where the dashboard is started via dotnet run or from the Docker image, the token can be retrieved from the console window that was used to start the app host. An URL also containing the token in a query string parameter t allows bypassing the login page and accessing the dashboard directly. Once authenticated, a cookie is created to avoid entering the token each time.

This login page is particularly useful when the dashboard is accessible over the local network or internet. However, for local development scenarios, some might find this step unnecessary or bothersome. Fortunately, there are two ways to disable it.

Disabling the .NET Aspire login page through an environment variable

You can use the DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS environment variable to disable the login page, for instance in a launch settings profile:



{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "https": {
      // [...]
      "environmentVariables": {
       // [...]
        "DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS": "true" // <-- ADD THIS LINE
      }
    }
  }
}

It's also possible to use it when starting the dashboard via Docker:



docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard -e DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS='true' mcr.microsoft.com/dotnet/nightly/aspire-dashboard:8.0.0-preview.6

Disabling the .NET Aspire login page programmatically

When building the DistributedApplication, you can inject a configuration value to disable the login page:



var builder = DistributedApplication.CreateBuilder(args);

builder.Configuration.AddInMemoryCollection(new Dictionary<string, string?>
{
    ["AppHost:BrowserToken"] = "",
});

Note that this method does not work with appsettings.json files because the DistributedApplication.CreateBuilder method overrides the empty token. With AddInMemoryCollection, you ensure that the configuration is modified after this logic.

References

.NET Aspire is the best way to experiment with Dapr during local development

Anthony Simmon — Sat, 04 May 2024 23:14:29 +0000

Not interested in reading the full article? Check out the complete code sample on GitHub instead.

Dapr provides a set of building blocks that abstract concepts commonly used in distributed systems. This includes secured synchronous and asynchronous communication between services, caching, workflows, resiliency, secret management and much more. Not having to implement these features yourself eliminates boilerplate, reduce complexity and allows you to focus on developing your business features.

You might be curious to see if Dapr can help you. Perhaps out of simple curiosity, because managing your services has become complex, or because you were asked to perform a proof of concept. Regardless of the reason, you have decided to learn and try Dapr.

You begin by understanding the basic concepts, perhaps even watching some video tutorials or online courses. You install the CLI and the required dependencies, hoping to quickly integrate the SDK into your applications. It takes you some time to understand how to set everything up. Before you know it, you've spent most of the day focusing on YAML-based infrastructure configuration.

Don't get me wrong, if you end up using Dapr in production, you will need to go through this learning process. However, in a situation where your time is limited and you just want to experiment, it can be frustrating to spend so much time on YAML configuration. Not to mention that you haven't yet determined the impact on the local development experience (troubleshooting, debugging, onboarding, etc.). Maybe some of your colleagues will initially be reluctant and believe that you're making their work more complicated than it already is.

Which option will offer you the best local development experience? Will it be the Multi-Run template? Dapr with Docker Compose? Or Dapr with Kubernetes via Minikube, Kind, Docker Desktop, or Helm?

In this article, I'll show you how to use Dapr with .NET Aspire for an unparalleled local development experience. We will create a few ASP.NET Core and Node.js services that will leverage service invocation, state management, and pub/sub. The benefits are:

A representation of your distributed system through compile-time constant, testable code.
A centralized OpenTelemetry web dashboard to browse your traces, logs and metrics.
A simple way to attach Dapr sidecars to your applications.
Little or no YAML configuration files.

Using .NET Aspire for Dapr will reduce the onboarding time for your developers. They can focus on using Dapr for feature development and spend less time setting up their local environment. Thanks to the integration with OpenTelemetry, it will be easier to troubleshoot interactions between multiple applications locally, which is usually done in cloud environments after the code is deployed.

Example of a Dapr distributed system with .NET Aspire

The goal of our Dapr experiment with .NET Aspire is to create three services and the .NET Aspire host project, which acts as the orchestrator:

Alice, an ASP.NET Core service that uses Dapr's service invocation to retrieve weather data from another service and caches it using the state store.
Bob, an ASP.NET Core service that returns fake weather data, then publishes a "weather forecast requested" event using pub/sub.
Carol, a Node.js Express web application that subscribes to "weather forecast requested" events.

The complete code ready for use is available in this GitHub repository ⭐. The README will guide you to install the prerequisites and start the services. There's too much code to show in this post, so I will only provide a few snippets and screenshots.

The code below is the .NET Aspire host project where we declare these services, Dapr components and their relationships, no YAML involved:

using Aspire.Hosting.Dapr;
using Microsoft.Extensions.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

var stateStore = builder.AddDaprStateStore("statestore");
var pubSub = builder.AddDaprPubSub("pubsub");

builder.AddProject<Projects.AspireDaprDemo_AliceService>("alice")
    .WithDaprSidecar()
    .WithReference(stateStore)
    .WithReference(pubSub);

builder.AddProject<Projects.AspireDaprDemo_BobService>("bob")
    .WithDaprSidecar()
    .WithReference(stateStore)
    .WithReference(pubSub);

builder.AddNpmApp("carol", Path.Combine("..", "AspireDaprDemo.CarolService"), "watch")
    .WithHttpEndpoint(port: 3000, env: "PORT")
    .WithEnvironment("NODE_TLS_REJECT_UNAUTHORIZED", builder.Environment.IsDevelopment() ? "0" : "1")
    .WithDaprSidecar()
    .WithReference(stateStore)
    .WithReference(pubSub);

builder.Build().Run();

When launched, the Aspire starts all the services and offers a complete view of the distributed system in the dashboard:

In this example, the Alice service exposes an endpoint /weatherforecast that triggers the interactions described above. Here's what the OpenTelemetry trace looks like when invoking this endpoint:

A developer joining the development team could quickly understand how the different components of the distributed system interact with each other. In this screenshot, we can see that the flaky Bob service returned an error and that Dapr automatically retried the operation.

To achieve this result, it is important that your applications are correctly instrumented with the OpenTelemetry SDK. Otherwise, only Dapr spans would have appeared.

.NET Aspire offers a better way to visualize OpenTelemetry traces than the default Zipkin instance provided with Dapr because not only are the traces visually clearer, but the dashboard also includes logs and metrics.

Dapr with .NET Aspire is configuration-free and easy to use

Normally, to configure Dapr, you need to create YAML configuration files that describe the applications, sidecars, and networking details such as TCP ports. With .NET Aspire, this is not required.

The communication between Alice and Bob, whose names were declared in the Aspire host project, is as simple as this thanks to the Dapr SDK (link to the full code):

// - "bob" is the name of the service declared in the Aspire host project
// - "weatherforecast" is the HTTP endpoint to invoke (URL path)
// - "client" is an instance of DaprClient available through dependency injection
var forecasts = await client.InvokeMethodAsync<WeatherForecast[]>(HttpMethod.Get, "bob", "weatherforecast");

No URLs were configured in appsettings.json or environment variables. Using the service name bob is the only constant required. Dapr is responsible for routing the request to the correct service.

The same is true for the state store and pub/sub. Connection details are only known to the Dapr sidecars, so the applications don't need to worry about them. This avoids the tedious management of configuration files.

Imagine having 10 services in your distributed system, along with 4 environments: local, dev, stg, and prod. This could represent 40 potential configuration files to maintain, with dozens of URLs and connection strings. Thanks to Dapr, you no longer have to worry about this.

Using the state store and pub/sub is just as simple:

// Retrieve the weather forecast from the state store "statestore" declared in the Aspire host
var cachedForecasts = await client.GetStateAsync<CachedWeatherForecast>("statestore", "cache");

// [...]
// Save the weather forecast in the state store under the key "cache"
await client.SaveStateAsync("statestore", "cache", new CachedWeatherForecast(forecasts, DateTimeOffset.UtcNow));

// Publish an event "WeatherForecastMessage" to the pub/sub "pubsub" declared in the Aspire host, with the topic "weather"
await client.PublishEventAsync("pubsub", "weather", new WeatherForecastMessage("Weather forecast requested!"));

This is a snippet of the Carol service which subscribes to the "weather" topic. Remember that both .NET Aspire and Dapr are language-agnostic:

// Events are received through HTTP POST requests (push delivery model)
app.post("/subscriptions/weather", (req, res) => {
  console.log("Weather forecast message received:", req.body.data);
  res.sendStatus(200);
});

How does .NET Aspire work with Dapr?

Using the WithDaprSidecar method on a resource instructs .NET Aspire to start an instance of the dapr executable.

// [...]
    .WithDaprSidecar()
    .WithReference(stateStore)
    .WithReference(pubSub);

The arguments passed to dapr depend on the number of components referenced by the service and the options that may be passed during the invocation of the methods above.

Here is the dapr command that is executed for the Alice service on my computer:

C:\dapr\dapr.exe run --app-id alice --resources-path C:\src\aspire-dapr-demo\resources --resources-path C:\Users\simmo\AppData\Local\Temp\aspire-dapr.xkxkzt4n.xcz\statestore --resources-path C:\Users\simmo\AppData\Local\Temp\aspire-dapr.xkxkzt4n.xcz\pubsub --app-port 5555 --dapr-grpc-port 58341 --dapr-http-port 58342 --metrics-port 58343 --app-channel-address localhost

Two key points to remember here:

The YAML code for built-in components in .NET Aspire, such as state store and pub/sub, is automatically generated in a temporary folder.
By default, random ports are assigned, so you don't have to remember them or worry about possible collisions.

If you want to learn more, the magic happens in the DaprDistributedApplicationLifecycleHook class in the .NET Aspire source code.

Subsequently, the orchestrated applications are passed environment variables that allow the Dapr SDK to communicate with the sidecars. This can be seen in the details of the resources on the Aspire dashboard:

Handling more complex Dapr scenarios

In this experiment, we used two Dapr components supported natively by .NET Aspire. However, it's possible to declare other types of components with the AddDaprComponent method:

builder.AddDaprComponent("localsecretstore", "secretstores.local.file", new DaprComponentOptions
{
    LocalPath = "/path/to/component-config.yaml" 
});

It's also possible to declare resources such as resilience policies and assign them to sidecars:

builder.AddProject<Projects.AspireDaprDemo_AliceService>("alice")
    .WithDaprSidecar(new DaprSidecarOptions
    {
        ResourcesPaths = "/path/to/resources-directory"
    })
    .WithReference(stateStore)
    .WithReference(pubSub);

References

Configure Renovate to handle nuspec files

Anthony Simmon — Sat, 04 May 2024 20:34:27 +0000

I recently mentioned that Renovate's NuGet manager only supports certain files by default, and .nuspec files are not among them. These are XML manifests that describe the metadata of a NuGet package. Although nowadays, SDK-style projects are sufficient for most cases to describe and generate NuGet packages, there are still many very popular projects that rely on .nuspec files, as shown by this search on GitHub.

.nuspec files can contain references to dependencies, making them important to consider in the Renovate update process, primarily for security reasons. Once again, we will use Renovate's extensibility with regular expressions to enable it to handle these files.

Renovate configuration for handling nuspec files

The following Renovate configuration:

Detects files with the .nuspec extension,
Uses a regex to parse the dependencies and their versions,
Applies the update management that would be used for NuGet.

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:best-practices"
  ],
  "enabledManagers": [
    "nuget",
    "custom.regex"
  ],
  "customManagers": [
    {
      "description": "Nuspec files manager",
      "customType": "regex",
      "fileMatch": ["\\.nuspec$"],
      "matchStringsStrategy": "any",
      "matchStrings": [
        "<dependency\\s+id=\"(?<depName>.*?)\"\\s+version=\"(?<currentValue>.*?)\"\\s*\\/>"
      ],
      "datasourceTemplate": "nuget",
      "versioningTemplate": "nuget"
    }
  ]
}

Testing the configuration

We can validate this configuration against a .nuspec file containing a reference to an old version of the C# MongoDB driver which contains a security vulnerability:

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <id>MyLibrary</id>
    <version>$version$</version>
    <description>Example nuspec file with an outdated, vulnerable dependency</description>
    <authors>johndoe</authors>
    <dependencies>
      <dependency id="MongoDB.Driver" version="2.18.0" />
    </dependencies>
  </metadata>
</package>

When running Renovate locally, we can see that the MongoDB.Driver dependency is detected and Renovate recommends updating it to version 2.25.0:

DEBUG: packageFiles with updates (repository=local)
       "config": {
         "regex": [
           {
             "deps": [
               {
                 "depName": "MongoDB.Driver",
                 "currentValue": "2.18.0",
                 "datasource": "nuget",
                 "versioning": "nuget",
                 "replaceString": "<dependency id=\"MongoDB.Driver\" version=\"2.18.0\" />",
                 "updates": [
                   {
                     "bucket": "non-major",
                     "newVersion": "2.25.0",
                     "newValue": "2.25.0",
                     "releaseTimestamp": "2024-04-12T21:27:47.967Z",
                     "newMajor": 2,
                     "newMinor": 25,
                     "updateType": "minor",
                     "branchName": "renovate/mongo-csharp-driver-monorepo"
                   }
                 ],
                 "packageName": "MongoDB.Driver",
                 "warnings": [],
                 "sourceUrl": "https://github.com/mongodb/mongo-csharp-driver",
                 "registryUrl": "https://api.nuget.org/v3/index.json",
                 "homepage": "https://www.mongodb.com/docs/drivers/csharp/",
                 "currentVersion": "2.18.0",
                 "isSingleVersion": true,
                 "fixedVersion": "2.18.0"
               }
             ],
             "matchStrings": [
               "<dependency\\s+id=\"(?<depName>.*?)\"\\s+version=\"(?<currentValue>.*?)\"\\s*\\/>"
             ],
             "matchStringsStrategy": "any",
             "datasourceTemplate": "nuget",
             "versioningTemplate": "nuget",
             "packageFile": "MyLibrary.nuspec"
           }
         ]
       }

References

Configure Renovate to update preview versions of NuGet packages

Anthony Simmon — Sat, 04 May 2024 20:32:25 +0000

By default, Renovate ignores preview versions of dependencies. For NuGet, a preview version is a package whose version contains a semantic suffix such as -alpha, -beta, -rc. There are some well-known NuGet packages that are only available in preview versions. For example, Aspire.Hosting will likely remain in preview until the release of .NET 9, StyleCop.Analyzers has been in beta for already 5 years, while OpenTelemetry.Instrumentation.GrpcNetClient and Azure.AI.OpenAI have never had a stable version.

Yet, these packages might be used today in production in your applications and services, and it is just as important to keep them updated as the other stable packages. To allow Renovate to update these packages, you must use the configuration property ignoreUnstable:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:best-practices"
  ],
  "enabledManagers": [
    "nuget"
  ],
  "packageRules": [
    {
      "matchManagers": ["nuget"],
      "matchPackageNames": ["Aspire.Hosting"],
      "description": ".NET Aspire is currently only available in preview",
      "ignoreUnstable": true // HERE
    }
  ]
}

In this example, we have a .NET Aspire host project for which we wish to keep the Aspire.Hosting dependency up to date. Here is the content of the csproj file:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <InvariantGlobalization>true</InvariantGlobalization>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting" Version="8.0.0-preview.2.23619.3" />
  </ItemGroup>
</Project>

When running Renovate locally, it is capable of finding a newer version of Aspire.Hosting, 8.0.0-preview.5.24201.12, which was released on the day I write these lines:

DEBUG: packageFiles with updates (repository=local)
       "config": {
         "nuget": [
           {
             "deps": [
               {
                 "datasource": "nuget",
                 "depType": "nuget",
                 "depName": "Aspire.Hosting",
                 "currentValue": "8.0.0-preview.2.23619.3",
                 "updates": [
                   {
                     "bucket": "non-major",
                     "newVersion": "8.0.0-preview.5.24201.12",
                     "newValue": "8.0.0-preview.5.24201.12",
                     "releaseTimestamp": "2024-04-09T14:50:53.883Z",
                     "newMajor": 8,
                     "newMinor": 0,
                     "updateType": "patch",
                     "branchName": "renovate/aspire.hosting-8.x"
                   }
                 ],
                 "packageName": "Aspire.Hosting",
                 "versioning": "nuget",
                 "warnings": [],
                 "sourceUrl": "https://github.com/dotnet/aspire",
                 "registryUrl": "https://api.nuget.org/v3/index.json",
                 "currentVersion": "8.0.0-preview.2.23619.3",
                 "isSingleVersion": true,
                 "fixedVersion": "8.0.0-preview.2.23619.3"
               }
             ],
             "packageFile": "MyProject.csproj"
           }
         ]
       }

References

Referencing external Docker containers in .NET Aspire using the new custom resources API

Anthony Simmon — Sat, 04 May 2024 17:13:51 +0000

Up until now, the application model of .NET Aspire was limited to two types of resources, namely executables and containers. The underlying DCP (Developer Control Plane) orchestrator is responsible for managing the lifecycle of these resources, including their creation, start, stop, and destruction.

David Fowler recently tweeted about the extensibility of the application model: ".NET Aspire is optimized for developers. With the application model, you can use .NET Code to build up an understanding of your application and its dependencies. This builds an object model that represents a resource graph."

However, .NET Aspire preview 5 changes the status quo by allowing the application model to reach a whole new level of extensibility. Now, it is possible to create custom resources, which can be fully controlled by your C# code and will appear in the dashboard. Among other things, you can:

Change their status (starting, running, finished),
Declare URLs to access these resources,
Add custom properties that can be used in lifecycle hooks,
Emit logs that will appear in the dashboard.

There are numerous potential applications for this new extensibility model, and I am eager to see what the community will do with it. For this article, we will add to the dashboard a container that is not controlled by .NET Aspire. One can imagine a development team that has not yet migrated their docker-compose.yml but would still like to see the containers and their logs appear in the .NET Aspire dashboard.

Another motivation would be for a developer to want a Docker container to continue its execution outside of an Aspire context, which is impossible today because Aspire destroys containers at the end of its execution.

Retrieving and displaying external container logs

We will create the following API:

IDistributedApplicationBuilder
    .AddExternalContainer("<resource-name>", "<external-container-name-or-id>");

We will use the command docker logs --follow CONTAINER-NAME-OR-ID to retrieve the logs of the external container. To facilitate the execution of the external docker process, we will use CliWrap instead of the primitive Process.

Here is what the resource will look like in the dashboard:

And here is the log output from the external container:

In this example, the external container is a persistent MongoDB instance configured as a single-node replica set as described in my article.

Building the external container custom resource API

In our .NET Aspire app host project, let's start by adding the definition of our custom resource:

internal sealed class ExternalContainerResource(string name, string containerNameOrId) : Resource(name)
{
    public string ContainerNameOrId { get; } = containerNameOrId;
}

Next, let's add the AddExternalContainer extension method:

internal static class ExternalContainerResourceExtensions
{
    public static IResourceBuilder<ExternalContainerResource> AddExternalContainer(this IDistributedApplicationBuilder builder, string name, string containerNameOrId)
    {
        builder.Services.TryAddLifecycleHook<ExternalContainerResourceLifecycleHook>();

        return builder.AddResource(new ExternalContainerResource(name, containerNameOrId))
            .WithInitialState(new CustomResourceSnapshot
            {
                ResourceType = "External container",
                State = "Starting",
                Properties = [new ResourcePropertySnapshot(CustomResourceKnownProperties.Source, "Custom")]
            })
            .ExcludeFromManifest();
    }
}

This method will have the effect of adding our resource to the dashboard with the status "Starting" and the source "Custom," which will allow us to distinguish Aspire-controlled resources from custom resources.

All that remains is to define the ExternalContainerResourceLifecycleHook lifecycle hook, which will be responsible for executing the command docker logs --follow CONTAINER-NAME-OR-ID, changing the resource status, and forwarding the logs to the dashboard:

internal sealed class ExternalContainerResourceLifecycleHook(ResourceNotificationService notificationService, ResourceLoggerService loggerService)
    : IDistributedApplicationLifecycleHook, IAsyncDisposable
{
    private readonly CancellationTokenSource _tokenSource = new();

    public Task BeforeStartAsync(DistributedApplicationModel appModel, CancellationToken cancellationToken = default)
    {
        foreach (var resource in appModel.Resources.OfType<ExternalContainerResource>())
        {
            this.StartTrackingExternalContainerLogs(resource, this._tokenSource.Token);
        }

        return Task.CompletedTask;
    }

    private void StartTrackingExternalContainerLogs(ExternalContainerResource resource, CancellationToken cancellationToken)
    {
        var logger = loggerService.GetLogger(resource);

        _ = Task.Run(async () =>
        {
            var cmd = Cli.Wrap("docker").WithArguments(["logs", "--follow", resource.ContainerNameOrId]);
            var cmdEvents = cmd.ListenAsync(cancellationToken);

            await foreach (var cmdEvent in cmdEvents)
            {
                switch (cmdEvent)
                {
                    case StartedCommandEvent:
                        await notificationService.PublishUpdateAsync(resource, state => state with { State = "Running" });
                        break;
                    case ExitedCommandEvent:
                        await notificationService.PublishUpdateAsync(resource, state => state with { State = "Finished" });
                        break;
                    case StandardOutputCommandEvent stdOut:
                        logger.LogInformation("External container {ResourceName} stdout: {StdOut}", resource.Name, stdOut.Text);
                        break;
                    case StandardErrorCommandEvent stdErr:
                        logger.LogInformation("External container {ResourceName} stderr: {StdErr}", resource.Name, stdErr.Text);
                        break;
                }
            }
        }, cancellationToken);
    }

    public ValueTask DisposeAsync()
    {
        this._tokenSource.Cancel();
        return default;
    }
}

Conclusion

This evolution of the .NET Aspire application model in this preview 5 opens new perspectives for developers. Combined with your own lifecycle hooks, flexibility and extensibility are greater than ever. The introduction of the new method IDistributedApplicationLifecycleHook.AfterEndpointsAllocatedAsync following the resolution of the GitHub issue #2155 I opened last February allows you to execute arbitrary code during a more advanced phase of the Aspire host lifecycle.

References

Automated NuGet package version range updates in .NET projects using Renovate

Anthony Simmon — Fri, 12 Apr 2024 13:30:00 +0000

In my previous post about how to locally test and validate Renovate configuration files, we saw how Renovate can be helpful in keeping our dependencies up-to-date. It recommended updates for the Microsoft.Extensions.Hosting package from 7.0.0 to 7.0.1 (minor) or 8.0.0 (major).

By default, the way Renovate handles NuGet package updates in .NET projects is suitable for the majority of cases. According to the Renovate NuGet manager documentation (a manager is a module that manages updates for a type of dependency), the following files are analyzed:

Project files .csproj, .fsproj, and .vbproj,
MSBuild files .props and .targets, including Directory.Build.props, Directory.Build.targets, and Directory.Packages.props,
.NET tool installation manifests dotnet-tools.json,
.NET SDK version definition files global.json.

Any reference to a NuGet package in these files will be analyzed by Renovate, and if a new version is available, a pull request will potentially be created to update it.

What is not specified in the Renovate NuGet manager documentation page is that it can only process packages referenced with the basic package version notation, for example:

<PackageReference Include="Microsoft.Extensions.Hosting" Version="7.0.0" />

However, specifying a package version in a .NET project can be much more advanced than that. Indeed, it's possible to specify a version range:

Notation	Applied rule	Description
1.0	x ≥ 1.0	Minimum version, inclusive
[1.0,)	x ≥ 1.0	Minimum version, inclusive
(1.0,)	x > 1.0	Minimum version, exclusive
[1.0]	x == 1.0	Exact version match
(,1.0]	x ≤ 1.0	Maximum version, inclusive
(,1.0)	x < 1.0	Maximum version, exclusive
[1.0,2.0]	1.0 ≤ x ≤ 2.0	Exact range, inclusive
(1.0,2.0)	1.0 < x < 2.0	Exact range, exclusive
[1.0,2.0)	1.0 ≤ x < 2.0	Mixed inclusive minimum and exclusive maximum version

Take, for example, the library OpenTelemetry.Instrumentation.Hangfire, which imports the Hangfire.Core library:

<PackageReference Include="Hangfire.Core" Version="[1.7.0,1.9.0)" />

Unfortunately, Renovate does not support NuGet version ranges by default. However, it is possible to extend its capabilities with regular expressions.

It's required to extract the dependency name and the current version. In my previous example, the dependency name is Hangfire.Core, and I will consider the current version to be the left side of the range, which is 1.7.0. You are free to decide which part of the range you wish to update.

Here's the regular expression that allows extracting the dependency name and the current version:

<PackageReference\s+Include="(?<depName>[^"]+)"\s+Version="\[(?<currentValue>[^,]+),.*"

depName and currentValue are mandatory group names that can be interpreted by Renovate to perform the update.

Let's update our Renovate file to include the custom regex manager with our regular expression. I've omitted any content from the file that's not relevant for this article.

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:best-practices"
  ],
  "enabledManagers": [
    "nuget",
    "custom.regex"
  ],
  "customManagers": [
    {
      "customType": "regex",
      "fileMatch": [
        "\\.csproj$"
      ],
      "matchStrings": [
        "<PackageReference\\s+Include=\"(?<depName>[^\"]+)\"\\s+Version=\"\\[(?<currentValue>[^,]+),.*\""
      ],
      "datasourceTemplate": "nuget",
      "versioningTemplate": "nuget"
    }
  ]
}

If we execute Renovate locally with our new configuration, we should see that Renovate is capable of identifying the 1.7.0 version of Hangfire.Core and proposes an update:

DEBUG: packageFiles with updates (repository=local)
       "config": {
         "regex": [
           {
             "deps": [
               {
                 "depName": "Hangfire.Core",
                 "currentValue": "1.7.0",
                 "datasource": "nuget",
                 "versioning": "nuget",
                 "replaceString": "<PackageReference Include=\"Hangfire.Core\" Version=\"[1.7.0,1.9.0)\"",
                 "updates": [
                   {
                     "bucket": "non-major",
                     "newVersion": "1.8.11",
                     "newValue": "1.8.11",
                     "releaseTimestamp": "2024-02-23T11:56:41.437Z",
                     "newMajor": 1,
                     "newMinor": 8,
                     "updateType": "minor",
                     "branchName": "renovate/hangfire-monorepo"
                   }
                 ],
                 "packageName": "Hangfire.Core",
                 "warnings": [],
                 "sourceUrl": "https://github.com/HangfireIO/Hangfire",
                 "registryUrl": "https://api.nuget.org/v3/index.json",
                 "homepage": "https://www.hangfire.io/",
                 "currentVersion": "1.7.0",
                 "isSingleVersion": true,
                 "fixedVersion": "1.7.0"
               }
             ],
             "matchStrings": [
               "<PackageReference\\s+Include=\"(?<depName>[^\"]+)\"\\s+Version=\"\\[(?<currentValue>[^,]+),.*\""
             ],
             "datasourceTemplate": "nuget",
             "versioningTemplate": "nuget",
             "packageFile": "Project.csproj"
           }
         ]
       }

The Renovate Regex manager has many other parameters, so be sure to check out the documentation.

References

TreatWarningsAsErrors and warnaserror are not the same

Anthony Simmon — Wed, 10 Apr 2024 13:30:00 +0000

At work, my team recently developed a custom MSBuild task designed to extract the OpenAPI specification from an ASP.NET Core application during compilation and validate it against our API design guidelines with Spectral.

When a Spectral rule is violated, the MSBuild task generates a warning. To ensure developers fix these issues, we planned for these warnings to be treated as errors in their CI pipeline. To achieve this, we relied on the TreatWarningsAsErrors property, which is already widely used in our projects.

Surprisingly, we discovered that the build of some projects did not fail despite the presence of warnings related to non-compliance with the OpenAPI specification. Here are the findings of my investigation.

`TreatWarningsAsErrors` only impacts the C# compiler

Indeed, the Microsoft documentation is clear on this matter:

TreatWarningsAsErrors only impacts the C# compiler, not any other MSBuild tasks in your csproj file. The warnaserror command line switch impacts all tasks.

If you want to ensure that there are absolutely no warnings in your build, you must include the -warnaserror argument:

dotnet build -warnaserror

`-warnaserror` can produce output on errors, `TreatWarningsAsErrors` does not

The same documentation states:

Secondly, the compiler doesn't produce any output on any warnings when TreatWarningsAsErrors is used. The compiler produces output when the warnaserror command line switch is used.

If you still wish to produce an assembly, despite there being warnings treated as errors, you can set TreatWarningsAsErrors to false and use -warnaserror instead.

References

C# Compiler Options to report errors and warnings

Locally test and validate your Renovate configuration files

Anthony Simmon — Tue, 09 Apr 2024 13:30:00 +0000

Renovate is an automated dependency management tool that can be used to keep your dependencies up-to-date. It can be configured to automatically create pull requests to update your dependencies, and it supports a wide range of package managers and platforms.

To use Renovate, you need to create a renovate.json configuration file. The creation process can take some time, as there are many configuration options available. Depending on the complexity of your project, the package managers you use, your platform (GitHub, GitLab, Azure DevOps, etc.), and your specific needs, you may need to go through several iterations to get a configuration that works well for you.

In this article, we will see how to test and validate your Renovate configuration files locally, to avoid having to push changes to your source control and wait for your pipeline to see if Renovate works as intended.

Prerequisites

We will be using the self-hosted version of Renovate distributed via npm, but you can adapt the scripts in this article to use the Docker version, or others. Make sure you have Node.js installed on your machine.

You also need a project with a Renovate configuration file, of course. For demonstration purposes, we will use a .NET project that contains a single dependency on an older version of Microsoft.Extensions.Hosting:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <!-- The most recent version of Microsoft.Extensions.Hosting is 8.0.0 as of this writing. -->
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="7.0.0" />
  </ItemGroup>
</Project>

Next, let's create a renovate.json file at the root:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:best-practices"
  ],
  "enabledManagers": [
    "nuget"
  ]
}

This simplistic Renovate configuration will serve as our example. Use your own Renovate configuration file if you already have one.

Launching Renovate locally

It is possible to run Renovate locally to test your configuration. To do this, we will use the following command for Linux and macOS:

LOG_LEVEL=debug npx renovate --platform=local --repository-cache=reset

For Windows using PowerShell Core, use this command:

pwsh -Command { $env:LOG_LEVEL="debug"; npx renovate --platform=local --repository-cache=reset }

The three important points to remember here are:

LOG_LEVEL=debug is used to obtain additional debugging information. Thanks to this environment variable, Renovate will display the updates available for the packages.
--platform=local is used to perform a dry run on the local computer.
--repository-cache=reset is used to force Renovate to ignore the cache. This can avoid incorrect results between your different modifications of your configuration.

Reading the Renovate output logs

In the .NET project of our example, we intentionally used an older version of Microsoft.Extensions.Hosting (7.0.0) so that Renovate could find an update. Here is an excerpt from the Renovate logs:

DEBUG: packageFiles with updates (repository=local)
       "config": {
         "nuget": [
           {
             "deps": [
               {
                 "datasource": "nuget",
                 "depType": "nuget",
                 "depName": "Microsoft.Extensions.Hosting",
                 "currentValue": "7.0.0",
                 "updates": [
                   {
                     "bucket": "non-major",
                     "newVersion": "7.0.1",
                     "newValue": "7.0.1",
                     "releaseTimestamp": "2023-02-14T13:21:52.713Z",
                     "newMajor": 7,
                     "newMinor": 0,
                     "updateType": "patch",
                     "branchName": "renovate/dotnet-monorepo"
                   },
                   {
                     "bucket": "major",
                     "newVersion": "8.0.0",
                     "newValue": "8.0.0",
                     "releaseTimestamp": "2023-11-14T13:23:17.653Z",
                     "newMajor": 8,
                     "newMinor": 0,
                     "updateType": "major",
                     "branchName": "renovate/major-dotnet-monorepo"
                   }
                 ],
                 "packageName": "Microsoft.Extensions.Hosting",
                 "versioning": "nuget",
                 "warnings": [],
                 "sourceUrl": "https://github.com/dotnet/runtime",
                 "registryUrl": "https://api.nuget.org/v3/index.json",
                 "homepage": "https://dot.net/",
                 "currentVersion": "7.0.0",
                 "isSingleVersion": true,
                 "fixedVersion": "7.0.0"
               }
             ],
             "packageFile": "RenovateDemo.csproj"
           }
         ]
       }

Notice how config.nuget[0].deps[0].updates contains two updates for Microsoft.Extensions.Hosting: one for a patch update (7.0.1) and one for a major update (8.0.0). This is the type of information you can expect to see when you run Renovate locally. The output might be more detailed or contain more information depending on your configuration and the packages you use.

Remove git hash from assembly informational version in .NET 8

Anthony Simmon — Mon, 08 Apr 2024 13:30:00 +0000

If you build your .NET projects with the .NET 8 SDK, you may have noticed that the assembly informational version now includes the git hash of the associated commit:

var informationalVersion = typeof(Program).Assembly
    .GetCustomAttribute<AssemblyInformationalVersionAttribute>()
    .InformationalVersion;

Console.WriteLine(informationalVersion);

// Prints something like
// 1.0.0+9aa8e4c69145f5b7b4b59c93f2a1ee5ea19b79f9

This is a breaking change in the .NET 8 SDK, which now includes Source Link by default. Source Link allows packages and applications to embed information about the source control of generated artifacts. This affects any target framework, as long as the code is compiled with the .NET 8 SDK.

If you had logic that uses the assembly informational version, it might not work at all anymore. To opt out of this feature, you need to add the following property in your .csproj file:

<PropertyGroup>
  <IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
</PropertyGroup>

Your custom HttpClient delegating handlers should be transient

Anthony Simmon — Fri, 05 Apr 2024 13:30:00 +0000

If you've ever encountered the following error, this article is for you:

InvalidOperationException: The 'InnerHandler' property must be null. 'DelegatingHandler' instances provided to 'HttpMessageHandlerBuilder' must not be reused or cached.

This means you are using the Microsoft.Extensions.Http library and have modified an HttpClient's handler pipeline by inserting a DelegatingHandler. As the error indicates, you cannot reuse a handler across multiple HttpClient instances. In other words, your DelegatingHandler cannot be a singleton. Here's an example of problematic code:

internal sealed class MyCustomDelegatingHandler : DelegatingHandler
{
    // Implementation omitted
}

// Registering the handler as a singleton is the mistake
services.AddSingleton<MyCustomDelegatingHandler>();

services.AddHttpClient("MyClient")
    .AddHttpMessageHandler<MyCustomDelegatingHandler>();

This code is also susceptible to the error mentioned above:

// This same instance will be used for all named HttpClient "MyClient"
var handler = new MyCustomDelegatingHandler();

services.AddHttpClient("MyClient")
    .AddHttpMessageHandler(() => handler);

Let's try to understand what's wrong here. The implementation of IHttpClientFactory, the service producing HttpClient instances, constructs the pipeline from multiple DelegatingHandlers making up an HttpClient. Each time an HttpClient is requested, the pipeline may be recreated.

Different DelegatingHandlers are linked to each other through the InnerHandler property, thanks to the CreateHandlerPipeline method. This method checks that the InnerHandler property isn't already set and throws the InvalidOperationException mentioned above if it is.

Handlers created as part of the IHttpClientFactory implementation are temporarily stored in a cache, for a duration equal to HttpClientFactoryOptions.HandlerLifetime. By default, this duration is 2 minutes. During this time, as many HttpClients as needed can be created and used without issue.

However, once the handler is removed from the cache, it will go through the CreateHandlerPipeline method again, and if it is a singleton, the InnerHandler property will already be set, leading to the exception being thrown.

If you control the lifecycle of the HttpClient and only create one throughout the lifespan of your application, you might never notice this issue. But often, developers overlook this aspect and are not aware of the exact context in which their HttpClient is used.

A particularly noticeable and error-prone example is that of typed clients. Typed clients are registered using the generic AddHttpClient<TClient> method (and its overloads), but in my experience, few developers realize that the TClient type becomes registered in services with a transient lifecycle. Thus, requesting this TClient multiple times will result in the creation of multiple HttpClients, causing the pipeline construction error if one of your delegating handlers is a singleton.

The solution is simple: ensure that the handler factory passed to the AddHttpMessageHandler method always returns a new instance.

// Registering the handler as a transient is the fix
services.AddTransient<MyCustomDelegatingHandler>();

services.AddHttpClient("MyClient")
    .AddHttpMessageHandler<MyCustomDelegatingHandler>();

// Or explicitly create a new instance each time
services.AddHttpClient("MyClient")
    .AddHttpMessageHandler(() => new MyCustomDelegatingHandler());

How to securely reverse-proxy ASP.NET Core web apps

Anthony Simmon — Thu, 04 Apr 2024 21:12:18 +0000

Kestrel is the solid, fast, and reliable web server that powers ASP.NET Core applications. It is entirely capable of serving as a front-facing web server, as proven by the Azure teams when they chose Kestrel and YARP to handle reverse-proxying all services hosted on Azure App Services.

However, it's very unlikely that .NET developers will directly expose their Kestrel-based web apps to the internet. Typically, we use other popular web servers like Nginx, Traefik, and Caddy to act as a reverse-proxy in front of Kestrel for various reasons:

To add a TLS termination layer: the reverse-proxy manages the TLS encryption and decryption (HTTPS),
To handle requests on a specific domain and port, often using a virtual host configuration,
To implement security features such as rate limiting, request filtering, HSTS, etc.,
To provide request compression and caching, depending on the end-user's browser capabilities,
For load balancing, failover support, and response transformation.

While these features can be configured with Kestrel, managing them across many web apps is more straightforward with a unified configuration point.

Understanding the need for header forwarding

When placing a reverse-proxy in front of our ASP.NET Core applications, the apps may lose access to certain original HTTP request information, like the client's IP address, specific HTTP headers, the original domain, and port. We need this information for the proper functioning of our applications.

This is where the concept of header forwarding comes into play. The reverse-proxy forwards the original HTTP request's information to the backend application server via specific headers. The most common forwarding headers are:

X-Forwarded-For: contains the original client's IP address,
X-Forwarded-Host: contains the original host requested by the client,
X-Forwarded-Proto: contains the original protocol (HTTP or HTTPS),
X-Forwarded-Prefix: contains the original path base used by the client.

Most ASP.NET Core applications, especially those that are containerized, listen on the loopback address and port 8080. Thus, X-Forwarded-Host and X-Forwarded-Proto are sometimes essential in scenarios where ASP.NET Core needs to generate URLs, such as in Razor templates or when generating redirect links in an OAuth2 authorization flow.

From a security perspective, X-Forwarded-For is also crucial. Without this header, your application would not be able to obtain the client's IP address, potentially affecting logging, your authentication and authorization stack, rate limiting logic, etc.

How to securely interpret X-Forwarded-* headers in ASP.NET Core

Ensuring ASP.NET Core securely interprets X-Forwarded-* headers is vital. Attackers could manipulate these headers to bypass security measures. How can we trust these header values?

Your reverse-proxy is responsible for stripping these headers from client requests. If not done, an end-user could, for instance, impersonate an IP address. By default, well-configured reverse-proxies don't accept them and populate these headers with reliable values like the TCP connection and original HTTP headers such as Host.

Avoid writing your logic to read and interpret X-Forwarded-* headers. ASP.NET Core already includes middleware that handles this securely:

// [...]
app.UseForwardedHeaders(); // <-- Add this line

app.UseAuthentication();
app.UseAuthorization();
// [...]

UseForwardedHeaders should be placed before any other middleware, especially before UseHsts, and can follow diagnostics and error handling middlewares.

Remember to configure the middleware options to specify which headers you wish to forward; otherwise, the middleware will not take any action. For example, to forward X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto:

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto | ForwardedHeaders.XForwardedHost;
});

The ForwardedHeadersOptions are very flexible, allowing you also to change the forwarding headers' names if you're not using the standard X-Forwarded-*.

The ForwardedHeadersMiddleware, inserted via UseForwardedHeaders, automatically updates HTTP request properties like RemoteIpAddress, Host, Scheme, and PathBase.

Restricting IP addresses of reverse-proxies authorized to forward headers

If you know the IP address or range of your reverse-proxy, you can specify them in the ForwardedHeadersOptions to ensure that the X-Forwarded-* headers come from a trusted source:

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    // 10.0.0.100 is the IP address of the reverse proxy
    // Use KnownProxies to add individual IP addresses you trust
    options.KnownProxies.Add(IPAddress.Parse("10.0.0.100"));

    // In case you have a range of IP addresses you trust, you can use KnownNetworks
    IPNetwork.Parse("10.0.0.0/24");
});

Forem: Anthony Simmon

Must-have resources for new .NET Aspire developers

.NET Aspire official documentation

Official videos on the Microsoft YouTube channels

Official code samples on GitHub

Community videos

David Fowler's experiments on GitHub

My blog posts

More blog posts, online resources and projects

Social networks

.NET Aspire's source code

Disabling .NET Aspire authentication to skip the login page

Disabling the .NET Aspire login page through an environment variable

Disabling the .NET Aspire login page programmatically

References

.NET Aspire is the best way to experiment with Dapr during local development

Example of a Dapr distributed system with .NET Aspire

Dapr with .NET Aspire is configuration-free and easy to use

How does .NET Aspire work with Dapr?

Handling more complex Dapr scenarios

References

Configure Renovate to handle nuspec files

Renovate configuration for handling nuspec files

Testing the configuration

References

Configure Renovate to update preview versions of NuGet packages

References

Referencing external Docker containers in .NET Aspire using the new custom resources API

Retrieving and displaying external container logs

Building the external container custom resource API

Conclusion

References

Automated NuGet package version range updates in .NET projects using Renovate

References

TreatWarningsAsErrors and warnaserror are not the same

TreatWarningsAsErrors only impacts the C# compiler

-warnaserror can produce output on errors, TreatWarningsAsErrors does not

References

Locally test and validate your Renovate configuration files

Prerequisites

Launching Renovate locally

Reading the Renovate output logs

Remove git hash from assembly informational version in .NET 8

Your custom HttpClient delegating handlers should be transient

How to securely reverse-proxy ASP.NET Core web apps

Understanding the need for header forwarding

How to securely interpret X-Forwarded-* headers in ASP.NET Core

Restricting IP addresses of reverse-proxies authorized to forward headers

References

`TreatWarningsAsErrors` only impacts the C# compiler

`-warnaserror` can produce output on errors, `TreatWarningsAsErrors` does not