定义自定义资源 URL

2025-05-20

在 .NET.NET Aspire中，公开终结点的资源仅配置主机和端口，直到运行时才知道这些主机和端口。如果需要访问这些终结点中的某个特定路径，尤其是从仪表板访问时，可以定义自定义资源 URL。还可以添加未绑定到任何终结点的自定义 URL。所有自定义 URL 仅在“运行”模式下可用，因为它们用于仪表板使用。本文演示如何定义自定义 URL。

默认终结点行为

默认情况下， .NET.NET Aspire 项目资源依赖于现有配置（如 Kestrel 或启动配置文件）来确定已配置终结点资源的主机和端口，并且终结点始终显示在仪表板上。

同样，可以使用 API 显式公开终结点 WithEndpoint 。通过此 API，可以指定资源的主机和端口，然后使用该主机和端口为该资源创建默认 URL。默认 URL 通常采用格式 <scheme>://<host>:<port>。若要省略主机端口，请使用以下方法之一：

有关详细信息，请参阅终结点扩展方法。

支持的资源类型

以下资源类型支持自定义资源 URL：

自定义资源 URL

在任何受支持的资源生成器上，使用适当的 WithUrl 重载、WithUrls 或 WithUrlForEndpoint API 来定义资源的自定义 URL。以下示例演示如何为项目资源设置自定义 URL：

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

小窍门

有一个重载可以接受 string，从而允许您传递任何 URL。这可用于定义与资源终结点不直接相关的自定义 URL。

前面的代码为变量分配项目引用 api ，该变量随后用于为 Admin Portal 路由创建自定义 URL。该方法 WithUrl 采用一个 ReferenceExpression 和一个显示名称作为参数。生成的 URL 在仪表板中可用，如以下屏幕截图所示：

自定义终结点 URL

Scalar 和 Swagger 都是增强终结点可用性的常见 API 服务。这些服务通过与声明的终结点绑定的 URL 进行访问。

若要自定义第一个关联的资源终结点的 URL，请使用 WithUrlForEndpoint 该方法。

如果要添加单独的 URL（甚至针对同一终结点），则需要调用 WithUrl 采用 ReferenceExpression 或内插字符串的重载，或调用 WithUrls 并将 URL 添加到 Urls 上下文中的列表。

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

前面的示例假设 api 项目资源已配置了一个 https 终结点。 WithUrlForEndpoint 方法更新与终结点关联的 ResourceUrlAnnotation 。在这种情况下，它将显示文本分配给 Scalar (HTTPS)，并将相对路径 /scalar 分配给 URL。

启动资源后，URL 在仪表板中可用，如以下屏幕截图所示：

或者，可以使用接受 Func<EndpointReference, ResourceUrlAnnotation> 回调的重载。这样就可以在目标 EndpointReference 实例上指定深层链接。

自定义多个资源网址

若要自定义资源的多个 URL，请使用 WithUrls 该方法。此方法允许你为资源指定多个 URL，每个 URL 都有其自己的显示文本。以下示例演示如何为项目资源设置多个 URL：

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();

前面的代码遍历为 api 项目资源定义的 URL，并分配显示文本（带有方案）。生成的 URL 在仪表板中可用，如以下屏幕截图所示：

.NET.NET Aspire 仪表板自定义有序 URL 和命名 URL。

小窍门

此 ResourceUrlsCallbackContext 公开了一个扩展方法，使你能够轻松访问名为“endpoints”的基础资源。对 GetEndpoint 上下文实例调用 API 以实现此目的。

URL 自定义生命周期

URL 自定义回调在应用程序模型生命周期中运行，尤其是在 BeforeResourceStartedEvent 事件处理期间。与终结点关联的 URL 变为活动状态，并在终结点本身处于活动状态后显示在仪表板上。仅当资源进入“正在运行”状态时，不与终结点关联的 URL 才会处于活动状态。这可确保在应用程序资源完全正常运行时准确表示和可用所有自定义 URL。

通过