Aspire 和启动配置文件

2025-10-02

Aspire 使用 AppHost 和服务项目中定义的 启动配置文件 来简化 Aspire 基于分布式应用程序调试和发布体验的多个方面进行配置的过程。

启动配置基础概述

从模板开发人员创建新的 .NET 应用程序时，通常会看到一个 Properties 目录，其中包含名为 launchSettings.json的文件。启动设置文件包含 启动配置文件的列表。每个启动简介是相关选项的集合，这些选项定义了您希望 dotnet 如何启动您的应用程序。

下面的代码是应用程序的 ASP.NET Core 文件中启动配置文件的示例。

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5130",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "https://localhost:7106;http://localhost:5130",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

上面的 launchSettings.json 文件定义了两个 启动配置文件，、http 和 https。每个都有自己的一组环境变量、启动 URL 和其他选项。启动 .NET 核心应用程序时，开发人员可以选择使用哪个启动配置文件。

dotnet run --launch-profile https

如果未指定启动配置文件，则默认选择第一个启动配置文件。可以使用 .NET 选项启动 --no-launch-profile Core 应用程序，而无需启动配置文件。 launchSettings.json 文件中的某些字段将转换为环境变量。例如，applicationUrl 字段被转换为 ASPNETCORE_URLS 环境变量，该变量控制 ASP.NET Core 要绑定到的地址和端口。

在 Visual Studio 可以在启动应用程序时选择启动配置文件，从而在手动调试问题时轻松地在配置方案之间进行切换：

当使用启动配置文件启动 .NET 应用程序时，名为 DOTNET_LAUNCH_PROFILE 的特殊环境变量将被填充为启动进程时所用的配置文件名称。

启动 Aspire AppHost 的配置文件

在 Aspire中，AppHost 只是一个 .NET 应用程序。因此，它具有 launchSettings.json 文件，就像任何其他应用程序一样。下面是从起始模板（dotnet new aspire-starter）创建新Aspire项目时生成的launchSettings.json文件示例。

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:17134;http://localhost:15170",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21030",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22057"
      }
    },
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:15170",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19240",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20154"
      }
    }
  }
}

模板Aspire具有与常规应用程序非常相似的ASP.NET Core集。 Aspire应用项目启动时，它会启动DistributedApplication并托管一个 Web 服务器，Aspire仪表板使用这个服务器来获取由Aspire协调的资源信息。

有关 AppHost 配置选项的信息，请参阅 Aspire AppHost 配置。

AppHost 启动配置文件和服务项目之间的关系

在 Aspire 中，AppHost 负责协调多个服务项目的启动。通过命令行或从 Visual Studio （或其他开发环境）运行 AppHost 时，将为 AppHost 选择启动配置文件。反过来，AppHost 将尝试在启动的服务项目中查找匹配的启动配置文件，并使用这些选项来控制服务项目的环境和默认网络配置。

当 AppHost 启动服务项目时，它不只是使用 --launch-profile 此选项启动服务项目。因此，不会为服务项目设置 DOTNET_LAUNCH_PROFILE 环境变量。这是因为 Aspire 修改 ASPNETCORE_URLS 环境变量（派生自 applicationUrl 启动配置文件中的字段）以使用不同的端口。默认情况下，Aspire 会在 ASP.NET Core 应用程序前插入一个反向代理，以使用 WithReplicas 方法实现应用程序的多实例运行。

其他设置（如 environmentVariables 字段中的选项）将传递到应用程序，而无需修改。

启动配置档选择控制

理想情况下，可以在 AppHost 和服务项目之间对齐启动配置文件名称，以便轻松地在由 AppHost 协调的所有项目上的配置选项之间切换。但是，可能需要控制特定项目使用的启动方案。 AddProject 扩展方法提供了执行此操作的机制。

var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.InventoryService>(
    "inventoryservice",
    launchProfileName: "mylaunchprofile");

前面的代码显示使用 inventoryservice 启动配置文件中的选项启动 .NET 资源（mylaunchprofile 项目）。启动配置文件优先逻辑如下所示：

如果已指定，则使用由 launchProfileName 参数指定的启动配置文件。
使用与 AppHost 同名的启动配置文件（通过读取 DOTNET_LAUNCH_PROFILE 环境变量确定）。
在 launchSettings.json中使用默认的（第一个）启动配置文件。
不要使用启动配置文件。

若要强制服务项目在没有启动配置文件的情况下启动，可以将 launchProfileName 方法中的 AddProject 参数设置为 null。

启动配置文件和终结点

在将 ASP.NET Core 项目添加到 AppHost 时，Aspire 将解析 launchSettings.json 文件，选择适当的启动配置文件，并根据 applicationUrl 字段中存在的 URL 在应用程序模型中自动生成终结点。修改自动注入 WithEndpoint 扩展方法的终结点。

var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.InventoryService>("inventoryservice")
       .WithEndpoint("https", endpoint => endpoint.IsProxied = false);

前面的代码演示如何禁用 Aspire 在 .NET Core 应用程序前面部署的反向代理，而是允许 .NET Core 应用程序直接通过 HTTP（S）响应请求。有关内部循环网络概述中的网络选项的详细信息，请参见。

另请参阅

Kestrel 配置的终结点

反馈

此页面是否有帮助？