API Proposal: Add support for multiple dynamic launch URLs and deep links in dashboard, i.e. IResourceBuilder.WithEndpointUrl()

kkirkfield commented 2 months ago

Background and Motivation

This API proposal aims to make it easier to have multiple dynamic launch URLs during development, and to deep link to URLs in the dashboard.

I am looking for feedback on this API. Thank you.

Proposed API

Here is the draft PR for this API proposal: https://github.com/dotnet/aspire/pull/5277

A new EndpointUrlAnnotation type is added to annotate URLs relative to dynamic endpoints. These annotations have properties to launch the URL at startup in the default system web browser, as well as to exclude the URL from the dashboard. URLs are set to not launch by default, but do show in the dashboard by default.

A new LaunchEndpointUrlLifecycleHook type is added to launch URLs after the endpoints are allocated.

ApplicationExecutor is updated to use these new annotations to construct URLs that are returned from the app host to the dashboard. This allows for deep links to parts of the app that were not previously possible with URLs from endpoints alone.

WithEndpointUrl() and similar HTTP and HTTPS variations are added to make it easy for developers to use these new features.

Usage Examples

Here is an example that launches a Scalar UI for interacting with Open API.

// AppHost/Program.cs

builder.AddProject<Projects.ApiService>("apiservice")
    .WithHttpsEndpointUrl(
        relativeUrl: "/scalar/v1",
        isLaunchUrl: true,
        excludeFromDashboard: false);

Alternative Designs

A previous version of this proposal just implemented launch URLs and did not include changes to the dashboard.

Another option instead of adding a new annotation type would be to modify the URL types used throughout the app host and dashboard to include the additional properties and relative URL. This seemed like a riskier option so I did not pursue it.

Risks

Developers new to Aspire could be confused with the difference between the existing Endpoint and the new EndpointUrl. We may want to give these new APIs a different name. For example: ShortcutUrl.

davidfowl commented 2 months ago

I would decouple the launch urls from the browser launching feature.

davidfowl commented 1 month ago

@kkirkfield are you still interested in finishing this change?

dotnet / aspire