.NET .NET Aspire 和启动配置文件

项目
01/23/2025

.NET .NET Aspire 利用应用主机和服务项目中定义的 启动配置文件 来简化为基于 .NET.NET Aspire分布式应用程序配置调试和发布体验的多个方面的过程。

启动配置文件基础知识

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

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

{
  "$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 的特殊环境变量将被填充为启动进程时所用的配置文件名称。

启动 .NET.NET Aspire 应用主机的配置文件

在 .NET Aspire中，AppHost 只是一个 .NET 应用程序。因此，它具有 launchSettings.json 文件，就像任何其他应用程序一样。下面是从初学者模板（dotnet new aspire-starter）创建新 .NET.NET 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",
        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21030",
        "DOTNET_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",
        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19240",
        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20154"
      }
    }
  }
}

.NET .NET Aspire 模板具有一组非常类似的 启动配置文件， 常规 ASP.NET Core 应用程序。启动 .NET.NET Aspire 应用项目时，它将启动 DistributedApplication 并托管由 .NET Aspire 仪表板使用的 Web 服务器，以提取由 .NET Aspire协调的资源的相关信息。

有关应用主机配置选项的信息，请参阅 .NET.NET Aspire 应用主机配置。

应用主机启动配置文件和服务项目之间的关系

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

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

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

启动配置档选择控制

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

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

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

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

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

启动配置文件和终结点

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

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

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

另请参阅

Kestrel 配置的终结点

通过