快速入门：构建您的第一个 .NET Aspire 应用程序

##前言

云原生应用程序通常需要连接到各种服务，例如数据库、存储和缓存解决方案、消息传递提供商或其他 Web 服务。.NET Aspire 旨在简化这些类型服务之间的连接和配置。在本快速入门中，您将了解如何创建 .NET Aspire Starter 应用程序模板解决方案。

##准备条件

要使用 .NET Aspire，您需要在本地安装以下软件：

.NET 8.0
.NET Aspire workload:
Use the Visual Studio installer
Use the dotnet workload install aspire command
Docker Desktop
Integrated Developer Environment (IDE) or code editor, such as:
Visual Studio 2022 Preview version 17.9 or higher (Optional)
Visual Studio Code (Optional)

##创建模板

要创建新的 .NET Aspire Starter 应用程序模板解决方案，您可以使用 Visual Studio 或 .NET CLI。

Visual Studio 提供了 .NET Aspire 项目模板，可以为您处理一些初始设置配置。请完成以下步骤为本快速入门创建项目：

在 Visual Studio 顶部，导航到“文件” “新建” “项目”。
在对话框窗口中，搜索Aspire并选择.NET Aspire Starter Application。选择下一步。
在“配置新项目”屏幕上：

输入项目名称AspireSample。
将其余值保留为默认值，然后选择“下一步”。

在附加信息屏幕上：

确保选择.NET 8.0（长期支持）。
确保选中“使用 Redis 进行缓存（需要 Docker）”并选择“创建”。

Visual Studio 创建了一个新的解决方案，该解决方案的结构是使用 .NET Aspire。

AspireSample目录：

└───📂 AspireSample
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

##.NET Aspire 应用程序主项目

*.AppHost项目负责充当协调器，并将IsAspireHost项目文件的属性设置为true

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\AspireSample.ApiService\AspireSample.ApiService.csproj" />
    <ProjectReference Include="..\AspireSample.Web\AspireSample.Web.csproj" />
  </ItemGroup>

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

</Project>

AspireSample.AppHost项目的Program.cs文件：

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.AddProject<Projects.AspireSample_Web>("webfrontend")
    .WithReference(cache)
    .WithReference(apiservice);

builder.Build().Run();

IDistributedApplicationBuilder通过调用创建一个实例。DistributedApplication.CreateBuilder(args)。
AddRedisContainer使用 name 进行调用"cache"以将 Redis 容器添加到应用程序，并将返回值分配给名为的变量cache，该变量的类型为IResourceBuilder<RedisContainerResource>。
调用AddProject给定的泛型类型参数和项目IServiceMetadata详细信息，将AspireSample.ApiService项目添加到应用程序模型中。这是 .NET Aspire 的基本构建块之一，它用于配置应用程序中项目之间的服务发现和通信。name 参数"apiservice"用于标识应用程序模型中的项目，稍后由想要与其通信的项目使用。
再次调用AddProject，这次将AspireSample.Web项目添加到应用程序模型中。它还链接多个调用来WithReference传递cache和apiservice变量。该WithReferenceAPI 是 .NET Aspire 的另一个基本 API，它将服务发现信息或连接字符串配置注入到要添加到应用程序模型的项目中。

##.NET Aspire 服务默认项目

*.ServiceDefaults项目是一个共享项目，用于管理在解决方案中的项目中重复使用的配置。该项目确保所有依赖服务共享相同的弹性、服务发现和 OpenTelemetry 配置。共享 .NET Aspire 项目文件包含IsAspireSharedProject设置为的属性true：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Library</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireSharedProject>true</IsAspireSharedProject>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />

    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="8.0.0-preview.1.23557.2" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.7.0-alpha.1" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.7.0-alpha.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.5.1-beta.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.GrpcNetClient" Version="1.5.1-beta.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.5.1-beta.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.5.1" />
  </ItemGroup>

</Project>

服务默认项目在IHostApplicationBuilder类型上公开一个名为的扩展方法AddServiceDefaults。模板中的服务默认项目是一个起点，您可以对其进行自定义以满足您的需求。有关详细信息，请参阅.NET Aspire 服务默认值。

##协调服务沟通

.NET Aspire 提供编排功能来协助配置应用程序不同部分之间的连接和通信。AspireSample.AppHost项目将AspireSample.ApiService和AspireSample.Web项目添加到应用程序模型中。它还声明了Blazor 前端的名称，以供 API 项目参考。此外，还添加了带有标签的 Redis 容器资源。这些名称用于配置应用程序中项目之间的服务发现和通信。“webfrontend”“apiservice”“redis”

前端应用程序定义了HttpClient用于与 API 项目通信的类型。

namespace AspireSample.Web;

public class WeatherApiClient(HttpClient httpClient)
{
    public async Task<WeatherForecast[]> GetWeatherAsync()
    {
        return await httpClient.GetFromJsonAsync<WeatherForecast[]>("/weatherforecast") ?? [];
    }
}

public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

配置为使用服务发现，请考虑AspireSample.Web项目的Program.csHttpClient文件中的以下代码：

using AspireSample.Web;
using AspireSample.Web.Components;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire components.
builder.AddServiceDefaults();
builder.AddRedisOutputCache("cache");

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddHttpClient<WeatherApiClient>(
    static client=> client.BaseAddress = new("http://apiservice"));

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
}

app.UseStaticFiles();

app.UseAntiforgery();

app.UseOutputCache();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();
    
app.MapDefaultEndpoints();

app.Run();

调用AddServiceDefaults，配置应用程序的共享默认值。
使用与将 Redis 容器添加到应用程序模型时使用的AddRedisOutputCache相同的调用。这将应用程序配置为使用 Redis 进行输出缓存。connectionName"cache"
调用AddHttpClient并将HttpClient.BaseAddress配置为"http://apiservice"。这是将 API 项目添加到应用程序模型时使用的名称，配置了服务发现后，它将自动解析为 API 项目的正确地址。

##在本地测试应用程序

示例应用程序现已准备好进行测试。想要验证以下内容：

使用服务发现从 API 项目检索天气数据并将其显示在天气页面上。
后续请求通过 .NET Aspire Redis 组件配置的输出缓存进行处理。

在 Visual Studio 中，通过右键单击“解决方案资源管理器”中的项目并选择“设置为启动项目”，将AspireSample.AppHost项目设置为启动项目。然后，按运行该应用程序。F5

在浏览器中从主页导航到天气页面。该页面应加载天气数据，并记下预报表中表示的一些值。
继续偶尔刷新页面 10 秒钟。10秒内返回缓存数据。最终，会出现一组不同的天气数据，因为数据是随机生成的并且缓存会更新。

##探索 .NET Aspire 仪表板

当您运行 .NET Aspire 应用程序时，还会启动一个仪表板，您可以使用它来监视应用程序的各个部分。仪表板应类似于以下屏幕截图：

访问左侧导航中的每个链接可查看有关 .NET Aspire 应用程序的不同信息：

项目：列出 .NET Aspire 应用程序中所有单个 .NET 项目的基本信息，例如应用程序状态、端点地址和加载的环境变量。
Containers：列出有关应用程序容器的基本信息，例如状态、图像标签和端口号。您应该会看到为输出缓存添加的 Redis 容器以及您提供的名称。
可执行文件：列出您的应用程序使用的正在运行的可执行文件。示例应用程序不包含任何可执行文件，因此它应该显示消息No runningexecutablesfound。
日志：
项目：显示应用程序中项目的输出日志。使用页面顶部的下拉菜单选择您想要显示日志的项目。
容器：显示应用程序中容器的日志。您应该会看到来自作为模板一部分配置的容器的 Redis 日志。如果您有多个容器，您可以使用页面顶部的下拉列表选择要显示日志的容器。
可执行文件：显示应用程序中可执行文件的日志。示例应用程序不包含任何可执行文件，因此这里没有任何内容可看。
结构化：以表格格式显示结构化日志。这些日志还支持基本过滤、自由格式搜索和日志级别过滤。您应该看到来自apiservice和的日志webfrontend。您可以通过选择行右端的“查看”按钮来展开每个日志条目的详细信息。
Traces：显示应用程序的跟踪，它可以跟踪通过您的应用程序的请求路径。找到/weather的请求，然后选择页面右侧的“查看” 。当请求穿过应用程序的不同部分时，仪表板应分阶段显示请求。
Metrics：显示您的应用程序公开的各种仪器和仪表及其相应的尺寸。指标根据过滤器的可用维度有条件地公开过滤器。