快速入門：構建您的第一個 .NET Aspire 應用程式

葡萄城技術團隊發表於2023-11-16

前言

雲原生應用程式通常需要連線到各種服務，例如資料庫、儲存和快取解決方案、訊息傳遞提供商或其他 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 Aspire 應用程式中所有單個 .NET 專案的基本資訊，例如應用程式狀態、端點地址和載入的環境變數。
Containers：列出有關應用程式容器的基本資訊，例如狀態、影像標籤和埠號。您應該會看到為輸出快取新增的 Redis 容器以及您提供的名稱。
可執行檔案：列出您的應用程式使用的正在執行的可執行檔案。示例應用程式不包含任何可執行檔案，因此它應該顯示訊息No runningexecutablesfound。
日誌：
專案：顯示應用程式中專案的輸出日誌。使用頁面頂部的下拉選單選擇您想要顯示日誌的專案。
容器：顯示應用程式中容器的日誌。您應該會看到來自作為模板一部分配置的容器的 Redis 日誌。如果您有多個容器，您可以使用頁面頂部的下拉選單選擇要顯示日誌的容器。
可執行檔案：顯示應用程式中可執行檔案的日誌。示例應用程式不包含任何可執行檔案，因此這裡沒有任何內容可看。
結構化：以表格格式顯示結構化日誌。這些日誌還支援基本過濾、自由格式搜尋和日誌級別過濾。您應該看到來自apiservice和的日誌webfrontend。您可以透過選擇行右端的“檢視”按鈕來展開每個日誌條目的詳細資訊。
Traces：顯示應用程式的跟蹤，它可以跟蹤透過您的應用程式的請求路徑。找到/weather的請求，然後選擇頁面右側的“檢視” 。當請求穿過應用程式的不同部分時，儀表板應分階段顯示請求。
Metrics：顯示您的應用程式公開的各種儀器和儀表及其相應的尺寸。指標根據過濾器的可用維度有條件地公開過濾器。