【译】发布 .NET Aspire 预览版 2（一）

原文 | Damian Edwards

翻译 | 郑子铭

自上个月宣布并推出 .NET Aspire 以来，我们收到的反馈非常惊人！通过问题和拉取请求对回购协议的参与一直激励着团队。我们正在深入了解开发人员在分布式云应用程序开发中如何使用（以及希望使用）.NET Aspire 或其他组件。社区已经做出了一些很棒的贡献，许多贡献也在进行中。我代表团队感谢您的兴奋和反馈！

.NET Aspire 预览版 2 现已推出！以下是此预览版中新增内容的摘要：

仪表板
- 所有资源类型现在都合并到一个“资源”视图中
- 新的详细信息窗格设计
- 所有资源类型的控制台日志现在合并到一个“控制台日志”视图中
- 添加到结构化日志视图的日志类别名称
- 对其他资源和开发服务的传出请求显示为资源/服务名称而不是 URL
托管和编排
- 容器现在支持配置在启动时传递给它们的参数
- 容器和可执行文件现在可以通过端点引用其他资源以进行服务发现配置
- 添加没有的项目
- 资源现在可以引用现有的 URI 端点来进行服务发现配置
- 支持添加 Node.js 应用程序作为资源
- 现在，无论有或没有副本托管，项目都使用启动配置文件中的端口
组件
- 组件包现在有单独的图标
- 新：添加了 MySqlConnector 组件
- 新：添加了 MongoDB 组件
- Azure SDK 组件现在默认启用分布式跟踪（服务总线除外）
部署
- Azure 开发人员 CLI 改进
- Aspir8：社区开发的工具，用于将 .NET Aspire 应用程序部署到 Kubernetes
Dapr
- 不再需要指定 Dapr sidecar 的 ID
- 对描述应用程序模型中所有 Dapr 组件的一流支持
- Azure 开发人员 CLI (AZD) 支持将使用 Dapr 的 .NET Aspire 应用部署到 Azure 容器应用 (ACA)

获取 .NET Aspire 预览版 2

要安装或升级到 .NET Aspire Preview 2，请执行以下步骤：

如果在 Windows 上并使用 Visual Studio 与 .NET Aspire 配合使用，请安装/更新到最新的 Visual Studio 2022 预览版（撰写本文时为 17.9.0 预览版 2.0）
- 确保在 Visual Studio 安装程序的“单独组件”选项卡下选择“.NET Aspire SDK（预览版）”组件：注意，您必须按照这些说明中的其余步骤更新到预览版 2

如果在 Windows 上安装了 Visual Studio 2022 17.8.x，但打算仅通过 .NET CLI (dotnet) 使用 .NET Aspire，请使用独立安装程序下载并安装 .NET 8.0.100 SDK
如果在 macOS 或 Linux 上，请下载并安装 .NET 8.0.100 SDK
从终端运行以下命令来更新 .NET Aspire 工作负载：

dotnet workload update
dotnet workload install aspire

请注意，如果您已经安装了 .NET Aspire 工作负载的 Preview 1 版本，您可能会看到消息，通知您工作负载已安装。这些可以安全地忽略。

有关安装 .NET Aspire 的详细说明，请参阅文档

更新后，您可以运行 dotnet Workload List 查看更新后的版本（注意：您的 Visual Sudio 版本可能有所不同）：

Installed Workload Id      Manifest Version                     Installation Source
----------------------------------------------------------------------------------------------

aspire                     8.0.0-preview.2.23619.3/8.0.100      SDK 8.0.100, VS 17.9.34310.174

更新现有应用程序

对于现有 .NET Aspire 应用程序，执行上述步骤以获取最新工作负载后，您将需要更改任何 Aspire 组件的包引用。将所有 Aspire 包引用（托管和组件）更新为 8.0.0-preview.2.23619.3，例如托管将更改为：

<PackageReference Include="Aspire.Hosting" Version="8.0.0-preview.2.23619.3" />

引用的所有其他包也应该更新到 Preview 2 版本。如果使用 Visual Studio，您还可以使用 NuGet 包管理器并更新通过 IDE 使用的所有包（请务必选中 UI 中的预发布复选框）。

API变更

此外，我们在预览版 2 中进行了一些托管 API 更改。在现有代码中，API 调用（例如 builder.AddPostgresContainer(...)）现在应更改为 builder.AddPostgres(...) 以保留相同的行为（有类似的更改）也适用于其他资源类型）。我们希望在“抽象”资源类型的概念（例如 Redis 服务器（例如 AddRedis(...)））和运行 Redis 的容器（例如 AddRedisContainer(...)）之间添加区别。 RedisContainer 等类型的构建器支持 WithEnvironment(...) 和 WithVolumeMount(...) 等扩展方法，而 RedisServer 等类型的构建器则不支持，因为预期 .NET Aspire 应用程序的部署工具可能会使用目标云环境中的托管资源类型，不支持以这种方式进行自定义。

此外，我们还删除了 builder.AddXYZConnection(...) 方法，其中 XYZ 是资源类型的名称。这些扩展是添加环境变量（例如 ConnectionString_myresource）的非常薄的包装。

仪表板更新

我们在 .NET Aspire 的初始预览版中得到了对仪表板的热烈响应！人们非常热衷于能够轻松地了解 .NET Aspire 如何帮助默认情况下使应用程序可观察，以及构成分布式系统的所有单独资源的状态。根据您的反馈，我们对预览 2 中的仪表板进行了以下更改。

资源和控制台日志的新组合视图

在预览版 1 中，仪表板上有单独的页面，用于查看配置为 .NET Aspire 应用程序一部分的项目、可执行文件和容器的详细信息。在预览版 2 中，这些已合并为一个“资源”页面，使您可以更轻松地在一个位置查看所有资源的状态和关键详细信息。 “名称”列现在包括项目和可执行文件的进程 ID 以及容器的容器 ID。 “源”列详细说明了项目和可执行文件的路径，对于容器，显示了图像名称和标签，以及容器端口（如果公开）。

控制台日志得到相同的处理，从而可以更轻松地从单个页面选择任何资源来查看控制台日志：

可停靠的详细信息窗格

现在使用新的详细信息窗格来显示相关项目的更多信息，例如资源的环境变量，或者结构化日志或跟踪范围的详细信息。该窗格可以停靠在当前视图的底部或侧面，从而可以更轻松地在当前视图中显示的不同项目的详细信息之间进行切换。

添加到结构化日志视图的日志类别名称

日志消息的类别名称现在显示在结构化日志视图的详细信息窗格中，从而可以轻松查看消息的来源：

发往已知目的地的传出请求将显示名称而不是 URL

现在，对已知目的地（例如由 Visual Studio 托管的其他资源和端点以支持开发体验（例如浏览器链接））的传出请求现在会在“跟踪”视图中自动解析和适当命名：

托管和编排更新配置容器启动参数

现在，您可以使用 IResourceBuilder.WithArgs 方法配置要传递到 AppHost 项目中配置的容器的参数。这些参数将在启动时传递给容器。以下是使用此功能的示例，取自新添加的数据库容器示例。

var builder = DistributedApplication.CreateBuilder(args);

var addressBookDb = builder.AddSqlServerContainer("sqlserver")
    // Mount the init scripts directory into the container.
    .WithVolumeMount("./sqlserverconfig", "/usr/config", VolumeMountType.Bind)
    // Mount the SQL scripts directory into the container so that the init scripts run.
    .WithVolumeMount("../DatabaseContainers.ApiService/data/sqlserver", "/docker-entrypoint-initdb.d", VolumeMountType.Bind)
    // Run the custom entrypoint script on startup.
    .WithArgs("/usr/config/entrypoint.sh")
    .AddDatabase("AddressBook");

所有资源类型之间的服务发现

现在可以使用 WithServiceBinding 方法配置容器和可执行文件以公开服务端点，然后使用 WithReference 将它们作为对其他资源的引用传递，并将其服务端点作为服务发现的配置注入。

var builder = DistributedApplication.CreateBuilder(args);

// Add customer API container built by partner team
var customerApi = builder.AddContainer("customerapi", image: "contoso.com/eshop/customers")
    .WithServiceBinding(containerPort: 8080, scheme: "http");

// Configure our storefront web project to reference the customer service API so that it can
// reference the service by name instead of by IP address, e.g. http://customerapi
var storeFront = builder.AddProject<Projects.Contoso_eShop_Storefront>("storefront")
    .WithReference(customerApi);

根据项目文件路径添加项目

在某些情况下，将 AppHost 项目中的项目引用添加到服务项目作为项目引用可能是不合需要的。现在，只需将项目文件路径传递给 AddProject 方法，就可以将项目添加为资源，而无需项目引用。这可以使在更复杂的源布局情况下（例如，从当前解决方案外部集成项目变得更容易）。当使用 git 子模块引入合作伙伴团队存储库的内容时。

var builder = DistributedApplication.CreateBuilder(args);

var pathBasedProject = builder.AddProject(
    name: "customerapi",
    // The project will be resolved relative to the AppHost project directory
    projectPath: "../../submodules/customerapi/src/CustomerApi/CustomerApi.csproj");

引用现有的 URI 端点以进行服务发现配置

从当前解决方案外部引用服务甚至由不同团队管理的另一种模式可以是使用专门为开发目的托管的服务的现有实例。您现在可以直接引用基于 HTTP 的服务，并使用服务发现所需的值配置使用资源：

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.AspireApp30_Web>("webfrontend")
    .WithReference(cache)
    // The app can reference this service simply via http://apiservice
    .WithReference("apiservice", new Uri("http://apiservice.v2.dev.contoso.com"));

支持添加 Node.js 应用程序作为资源

现在支持将基于 Node.js 的应用程序配置到 .NET Aspire AppHost 项目中。 AddNodeApp 和 AddNpmApp 方法可用于轻松地将 Node.js 应用程序包含在 Aspire AppHost 项目中，例如基于 React 的前端。包含的 Node.js 应用程序可以参与服务发现和连接字符串配置，并将注入仪表板 OTLP 端点 URL 以启用 OpenTelemetry。要将应用程序配置为部署为容器，请对返回的资源调用 AsDockerFileInManifest 方法。

Aspire with Node.js 示例已更新为使用此内置支持，并演示了如何配置 Node.js 应用程序以将 OpenTelemetry 跟踪导出到 Aspire 仪表板。

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedisContainer("cache");

var apiservice = builder.AddProject<Projects.ApiService>("apiservice");

builder.AddNodeApp("webapp", "../webapp/app.js")
    .WithReference(apiservice)
    .WithReference(cache)
    // Dynamically assign an http port for the the Node.js app.
    // The port will be set in the 'PORT' environment variable.
    .WithServiceBinding(scheme: "http", env: "PORT")
    .AsDockerfileInManifest();

项目现在一致使用其启动配置文件中指定的端口

启动 AppHost 项目时，Aspire.Hosting 会在所有配置的服务之前启动反向代理，以便可以执行对配置的副本进行负载平衡等任务。项目应用程序本身的实例将被分配随机端口来侦听，代理会将客户端请求转发到该端口。现在，在开发过程中本地运行时，代理将使用项目启动配置文件中指定的端口（即 Properties/launchSettings.json 文件中的“applicationUrl”属性）作为传入端口。这意味着您用于访问项目的本地主机 URL 现在应该在开发过程中保持一致，因为它由项目的启动配置文件控制，无论是直接启动项目，还是通过 AppHost 项目启动它，无论是否有副本。