Define custom resource URLs

2025-05-19

In .NET Aspire, resources that expose endpoints only configure host and port, which aren't known until run time. If you need to access a specific path on one of these endpoints—especially from the dashboard—you can define custom resource URLs. You can also add custom URLs that aren't tied to any endpoint. All custom URLs are only available in "run" mode, since they're meant for dashboard use. This article demonstrates how to define custom URLs.

Default endpoint behavior

By default, .NET Aspire project resources rely on existing configurations such as Kestrel or launch profiles to determine the host and port of a resource for a configured endpoint—and the endpoints are always displayed on the dashboard.

Likewise, you can explicitly expose endpoints using the WithEndpoint API. This API allows you to specify the host and port for a resource, which is then used to create the default URL for that resource. The default URL is typically in the format <scheme>://<host>:<port>. To omit the host port, use one of the following methods:

For more information, see Endpoint extension methods.

Supported resource types

Custom resource URLs are supported for the following resource types:

Customize resource URLs

Use the appropriate WithUrl overload, WithUrls, or WithUrlForEndpoint APIs on any supported resource builder to define custom URLs for a resource. The following example demonstrates how to set a custom URL for a project resource:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.AspireApp_Api>("api");

api.WithUrl("/admin", "Admin Portal");

builder.Build().Run();

Tip

There's an overload that accepts a string allowing you to pass any URL. This is useful for defining custom URLs that aren't directly related to the resource's endpoint.

The preceding code assigns a project reference to the api variable, which is then used to create a custom URL for the Admin Portal route. The WithUrl method takes a ReferenceExpression and a display name as parameters. The resulting URL is available in the dashboard as shown in the following screenshot:

Customize endpoint URL

Both Scalar and Swagger are common API services that enhance the usability of endpoints. These services are accessed via URLs tied to declared endpoints.

To customize the URL for the first associated resource endpoint, use the WithUrlForEndpoint method.

If you want to add a separate URL (even for the same endpoint) you need to call the WithUrl overload that takes a ReferenceExpression or interpolated string, or call WithUrls and add the URL to the Urls list on the context.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.AspireApp_Api>("api")
    .WithUrlForEndpoint("https", url =>
    {
        url.DisplayText = "Scalar (HTTPS)";
        url.Url = "/scalar";
    });

builder.Build().Run();

The preceding example assumes that the api project resource has an https endpoint configured. The WithUrlForEndpoint method updates the ResourceUrlAnnotation associated with the endpoint. In this case, it assigns the display text to Scalar (HTTPS) and assigns the relative /scalar path to the URL.

When the resource is started, the URL is available in the dashboard as shown in the following screenshot:

Alternatively, you could use the overload that accepts a Func<EndpointReference, ResourceUrlAnnotation> as a callback. This allows you to specify deep-links on target EndpointReference instances.

Customize multiple resource URLs

To customize multiple URLs for a resource, use the WithUrls method. This method allows you to specify multiple URLs for a resource, each with its own display text. The following example demonstrates how to set multiple URLs for a project resource:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.AspireApp_Api>("api")
    .WithUrls(context =>
    {
        foreach (var url in context.Urls)
        {
            if (string.IsNullOrEmpty(url.DisplayText))
            {
                url.DisplayText = $"API ({url.Endpoint?.Scheme?.ToUpper()})";
            }
        }
    });

builder.Build().Run();

The preceding code iterates through the URLs defined for the api project resource and assigns a display text with scheme. The resulting URLs are available in the dashboard as shown in the following screenshot:

.NET Aspire dashboard custom ordered and named URLs.

Tip

The ResourceUrlsCallbackContext exposes an extension method that enables you to easily access the underlying resource named endpoints. Call the GetEndpoint API on a context instance to achieve this.

URL customization lifecycle

URL customization callbacks run during the application model lifecycle, specifically during the BeforeResourceStartedEvent event processing. URLs associated with endpoints become active and appear on the dashboard once the endpoint itself becomes active. URLs not associated with endpoints become active only when the resource enters the "Running" state. This ensures that all custom URLs are accurately represented and available when the application resources are fully operational.

Share via