README.md

AspireRunner.AspNetCore

A library for running the Aspire Dashboard alongside ASP.NET Core apps.

The dashboard can display OpenTelemetry data (traces, metrics, and logs) from any application. This is intended to be used for local development only.

Important

The package depends on the dashboard being pre-installed on the machine using either the dotnet tool or the installer package. For more info, refer to the installer package docs

Example usage

using AspireRunner.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// ...

if (builder.Environment.IsDevelopment())
{
    // bind from configuration (appsettings.json, etc)
    builder.Services.AddAspireDashboard(options => builder.Configuration.GetSection("AspireDashboard").Bind(options));

    // or pass an options instance
    builder.Services.AddAspireDashboard(new AspireDashboardOptions
    {
        Frontend = new FrontendOptions
        {
            EndpointUrls = "https://localhost:5020"
        },
        Otlp = new OtlpOptions
        {
            EndpointUrl = "https://localhost:4317"
        },
        Runner = new RunnerOptions
        {
            LaunchBrowser = true
        }
    });
}

var app = builder.Build();

// ...

await app.RunAsync();

Note

By default, The runner will download the dashboard to the user's .dotnet directory (~/.dotnet/.AspireRunner), this can be changed by setting the ASPIRE_RUNNER_PATH environment variable.

Configuration

The runner can be configured with the AspireDashboardOptions class, which contains a subset of the options supported by the Aspire dashboard, but also has runner-specific options under the Runner property:

• PipeOutput (bool): When enabled, the runner will pipe the output of the dashboard process to the logger.
• LaunchBrowser (bool): When enabled, the runner will attempt to launch the dashboard in the default browser on startup.
• SingleInstanceHandling (enum): Controls how the runner should handle multiple instances of the dashboard process:
  1. WarnAndExit: Logs a warning and exits if an existing instance is found. (default value)
  2. Ignore: Disables checking for running instances of the Aspire Dashboard. Note that new instances will fail to start if an existing one is using the same port
  3. ReplaceExisting: Kills any existing instance before starting a new one.
• AutoUpdate (bool): When enabled, the runner will automatically check and update the dashboard to the latest version at startup.
• PreferredVersion (string): The version of the dashboard to download/run. If not specified or invalid, the latest version will be used.
• RestartOnFailure (bool): When enabled, the runner will automatically restart the dashboard if it exits unexpectedly.
• RunRetryCount (int): The number of times to retry running the dashboard if it fails to start
• RunRetryDelay (int): The delay between retry attempts to restart the dashboard (in seconds).
• Mode (enum): Defines how the dashboard runs relative to the host application:
  1. Embed: Dashboard is tied to the host; it starts and stops with the host and can be replaced when the host restarts. (default value)
  2. Standalone: Dashboard runs as a standalone process; it is not terminated when the host stops, and the host reuses an existing dashboard if one is already running.