指南：在 ASP.NET Core 中使用 .NET Aspire 傳訊整合

發行項
12/12/2024

雲端原生應用程式通常需要可調整的傳訊解決方案，以提供訊息佇列和主題和訂用帳戶等功能。 .NET Aspire 的整合功能可簡化與各種訊息服務提供者的連接過程，例如 Azure Service Bus。在本教學課程中，您將建立 ASP.NET Core 應用程式，該應用程式會使用 .NET Aspire 整合來連線到 Azure Service Bus 來建立通知系統。提交的訊息將會傳送至服務總線主題，供訂閱者取用。您將瞭解如何：

建立設定為使用 .NET Aspire 整合的基本 .NET 應用程式
新增 .NET Aspire 整合以連線至 Azure Service Bus
設定及使用 .NET.NET Aspire 整合功能來傳送和接收數據

先決條件

若要使用 .NET.NET Aspire，您需要在本地安裝下列項目：

.NET 8.0 或 .NET 9.0
符合 OCI 規範的容器運行時間，例如：
- Docker 桌面或 Podman。如需詳細資訊，請參閱容器運行時間。
整合式開發人員環境（IDE）或程式碼編輯器，例如：
- Visual Studio 2022 17.9 版或更高版本（選用）
- Visual Studio Code （選擇性）
  - C# Dev Kit：擴充功能（選擇性）
- JetBrains Rider 搭配 .NET.NET Aspire 外掛程式（選用）

如需詳細資訊，請參閱 .NET.NET Aspire 設定和工具和 .NET.NET Aspire SDK。

除了上述必要條件之外，您還需要安裝 Azure CLI。若要安裝 Azure CLI，請遵循 Azure CLI 安裝指南中的指示，。

設定 Azure Service Bus 帳戶

在本教學課程中，您將需要存取已設定主題和訂用帳戶的 Azure Service Bus 命名空間。使用下列其中一個選項來設定需要資源：

Azure 入口網站：使用主題和訂用帳戶建立服務總線帳戶。

或者：

Azure CLI：在 Azure CLI 或 CloudShell 中執行下列命令，以設定所需的 Azure Service Bus 資源：

az group create -n <your-resource-group-name> --location eastus
az servicebus namespace create -g <your-resource-group-name> --name <your-namespace-name> --location eastus
az servicebus topic create -g <your-resource-group-name> --namespace-name <your-namespace-name> --name notifications
az servicebus topic subscription create -g <your-resource-group-name> --namespace-name <your-namespace-name> --topic-name notifications --name mobile

注意

將占位符 your-resource-group-name 和 your-namespace-name 替換為您自己的值。服務匯流排命名空間名稱必須在 Azure中全域唯一。

Azure 驗證

本快速入門可以使用無密碼身份驗證或連接字串來完成。無密碼連接會使用 Azure Active Directory 和角色型存取控制（RBAC）來連接到 Service Bus 命名空間。您不需要擔心在程式碼、組態檔或安全記憶體中具有硬式編碼連接字串，例如 Azure Key Vault。

您也可以使用連接字串來連線到服務總線命名空間，但對於真實世界應用程式和生產環境，建議使用無密碼的方法。如需詳細資訊，請參閱驗證和授權，或瀏覽無密碼概觀頁面。

無密碼（建議）
連接字串

在您的服務匯流排命名空間上，將下列角色指派給您以登入 Visual Studio 或 Azure CLI 的用戶帳戶：

服務總線數據擁有者：指派 Azure RBAC 角色

建立範例解決方案

若要建立新的 .NET Aspire 入門應用程式，您可以使用 Visual Studio、Visual Studio Code或 .NET CLI。

Visual Studio 提供 .NET Aspire 範本，為您處理一些初始設定組態。完成下列步驟以建立本快速入門的專案：

在 Visual Studio頂端，瀏覽至 [檔案]>[新建>專案]。
在對話框視窗中，搜尋，然後選取 [入門應用程式] 。選取 下一步。
在 配置新專案 頁面：
- 輸入 項目名稱AspireSample。
- 將值的 rest 保留為預設值，然後選取 [下一步]。
在「其他資訊」畫面上：
- 請確認已選中 .NET 9.0（標準字詞支援）。
- 確保已核取使用進行快取（需要支援的容器執行環境），然後選取 [建立] 。
- 選擇性地，您可以選擇 建立測試項目。如需詳細資訊，請參閱撰寫第一個 .NET.NET Aspire 測試。

Visual Studio 會建立設計為使用 .NET Aspire的新解決方案。

Visual Studio Code 提供 .NET Aspire 項目範本，為您處理一些初始設定組態。完成下列步驟以建立本快速入門的專案：

從新實例（未開啟資料夾），選取 [建立專案] 按鈕。
選取 .NET.NET Aspire 入門應用程式 範本。

如果您尚未安裝 .NET.NET Aspire 模板，請執行下列 dotnet new install 命令：

dotnet new install Aspire.ProjectTemplates

上述 .NET CLI 命令可確保您有可用的 .NET Aspire 範本。若要從範本建立 .NET.NET Aspire 入門應用程式，請執行下列 dotnet new 命令：

dotnet new aspire-starter --use-redis-cache --output AspireSample

如需詳細資訊，請參閱 dotnet new。 .NET CLI 會建立結構化的新解決方案，以使用 .NET Aspire。

新增 Worker Service 專案

接下來，將 Worker Service 專案新增至方案，以擷取和處理來自 Azure Service Bus的訊息。

在方案總管中，以滑鼠右鍵按兩下最上層 AspireSample 方案節點，然後選取 [[新增>新增專案]。
搜尋並選取 Worker Service 範本，然後選擇 [下一步]。
針對 項目名稱，輸入 AspireSample.WorkerService，然後選取 [下一步]。
在 [其他資訊 頁面：
- 請確認已選取 .NET 9.0。
- 請確定已核取 列入 .NET.NET Aspire 協作，然後選取建立。

Visual Studio 將專案新增至您的方案，並使用新的程式代碼行更新 AspireSample.AppHost 項目的 Program.cs 檔案：

builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");

Visual Studio 工具組新增這一行代碼，以向 IDistributedApplicationBuilder 對象註冊您的新專案，這使您能夠探索稍後的協作功能。

從 [方案總管]Visual Studio Code中，選取方案名稱旁的 [+] 按鈕，將新專案新增至方案：
若要篩選專案範本，請在搜尋方塊中輸入 工作人員，然後選取搜尋結果中的 Worker Service 範本：
選擇 Worker Service 樣本，並將項目名稱輸入為 AspireSample.WorkerService。
選取 [[預設目錄]，以在與方案相同的目錄中建立專案。
選擇 建立專案 來將專案新增至方案。
在 [方案總管] 中找到 [AspireSample.AppHost] 專案，然後按一下滑鼠右鍵並選擇 [新增專案參考]。
在呼叫 builder.Build().Run();之前，將下列程式代碼行新增至 AspireSample.AppHost 專案中的 Program.cs 檔案：
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

在應用程式的根目錄中，使用 dotnet new 命令來建立新的 Worker Service 應用程式：
```
dotnet new worker --name AspireSample.WorkerService
```

使用 dotnet sln 命令，將專案新增至方案：

dotnet sln AspireSample.sln add AspireSample.WorkerService/AspireSample.WorkerService.csproj

使用 dotnet add 命令，在 .AppHost 專案與 .WorkerService 專案之間新增項目參考。

dotnet add AspireSample.AppHost/AspireSample.AppHost.csproj reference AspireSample.WorkerService/AspireSample.WorkerService.csproj

在呼叫 builder.Build().Run();之前，將下列程式代碼行新增至 AspireSample.AppHost 專案中的 Program.cs 檔案：
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

如果最上層目錄命名為 aspire傳訊，則已完成的解決方案結構應該如下所示：

└───📂 aspire-messaging
     ├───📂 AspireSample.WorkerService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.WorkerService.csproj
     │    ├─── Program.cs
     │    └─── Worker.cs
     ├───📂 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

在 API 中新增 .NET.NET Aspire 整合

將 .NET Aspire Azure Service Bus 整合新增至 AspireSample.ApiService 應用程式：

在 [方案總管]中，按兩下 AspireSample.ApiService.csproj 檔案以開啟其 XML 檔案。

將下列 <PackageReference> 專案新增至 <ItemGroup> 專案：

<ItemGroup>
    <PackageReference Include="Aspire.Azure.Messaging.ServiceBus"
                      Version="8.0.1" />
</ItemGroup>

在 [方案總管]中，右鍵單擊 AspireSample.ApiService 專案，然後選擇 [新增 NuGet 套件]：
輸入 Aspire。Azure。Messaging.ServiceBus 在搜尋方塊中，然後從清單中選取套件。
選取 （最新版） 版本以安裝套件。

dotnet add package Aspire.Azure.Messaging.ServiceBus

在 AspireSample.ApiService 專案的 Program.cs 檔案中，新增對 AddAzureServiceBusClient 擴充方法的呼叫，取代對 AddServiceDefaults的現有呼叫：

// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");

如需詳細資訊，請參閱 AddAzureServiceBusClient。

此方法會完成下列工作：

向 DI 容器註冊 ServiceBusClient，以連線到 Azure Service Bus。
自動為個別服務啟用對應的健康情況檢查、記錄和遙測。

在相同專案的 appsettings.json 檔案中，新增對應的連接資訊：

無密碼（建議）
連接字串

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_namespace}.servicebus.windows.net"
  }
}

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "Endpoint=sb://{your_namespace}.servicebus.windows.net/;
          SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey"
  }
}

注意

請務必將服務 URI 中的 {your_namespace} 取代為您自己的服務總線命名空間名稱。

建立 API 端點

API 必須提供端點來接收數據，並將其發佈至服務總線主題，並廣播給訂閱者。將下列端點新增至 AspireSample.ApiService 專案，以將訊息傳送至服務總線主題。使用下列 C# 程式代碼取代 Program.cs 檔案的所有內容：

using Azure.Messaging.ServiceBus;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");

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

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

app.MapPost("/notify", static async (ServiceBusClient client, string message) =>
{
    var sender = client.CreateSender("notifications");

    // Create a batch
    using ServiceBusMessageBatch messageBatch =
        await sender.CreateMessageBatchAsync();

    if (messageBatch.TryAddMessage(
            new ServiceBusMessage($"Message {message}")) is false)
    {
        // If it's too large for the batch.
        throw new Exception(
            $"The message {message} is too large to fit in the batch.");
    }

    // Use the producer client to send the batch of
    // messages to the Service Bus topic.
    await sender.SendMessagesAsync(messageBatch);

    Console.WriteLine($"A message has been published to the topic.");
});

app.MapDefaultEndpoints();

app.Run();

將 .NET Aspire 整合至 Worker Service

將 .NET Aspire Azure Service Bus 整合新增至 AspireSample.WorkerService 專案。請按照您之前將 Aspire.Azure.Messaging.ServiceBus NuGet 套件新增到 AspireSample.ApiService 專案時所採取的相同步驟進行操作。新增之後，您可以設定工作服務來處理來自服務匯流排主題的訊息。

在 AspireSample.WorkerService 專案的 Program.cs 檔案中，將現有的程式代碼取代為以下程式代碼：

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Run();

AddAzureServiceBusClient 方法會完成下列工作：

向 DI 容器註冊 ServiceBusClient，以連線到 Azure Service Bus。
自動為個別服務啟用對應的健康情況檢查、記錄和遙測。

在 AspireSample.WorkerService 專案的 appsettings.json 檔案中，新增對應的聯機資訊：

無密碼（建議）
連接字串

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_namespace}.servicebus.windows.net"
  }
}

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "Endpoint=sb://{your_namespace}.servicebus.windows.net/;
        SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey"
  }
}

注意事項

請務必將服務 URI 中的 {your_namespace} 取代為您自己的服務總線命名空間名稱。

處理來自訂閱者的訊息

當新的訊息放置在 messages 佇列時，工作者服務應該擷取、處理和刪除訊息。更新 Worker.cs 類別以符合下列程式代碼：

using Azure.Messaging.ServiceBus;

namespace AspireSample.WorkerService;

public sealed class Worker(
    ILogger<Worker> logger,
    ServiceBusClient client) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var processor = client.CreateProcessor(
                "notifications",
                "mobile",
                new ServiceBusProcessorOptions());

            // Add handler to process messages
            processor.ProcessMessageAsync += MessageHandler;

            // Add handler to process any errors
            processor.ProcessErrorAsync += ErrorHandler;

            // Start processing
            await processor.StartProcessingAsync();

            logger.LogInformation("""
                Wait for a minute and then press any key to end the processing
                """);

            Console.ReadKey();

            // Stop processing
            logger.LogInformation("""

                Stopping the receiver...
                """);

            await processor.StopProcessingAsync();

            logger.LogInformation("Stopped receiving messages");
        }
    }

    async Task MessageHandler(ProcessMessageEventArgs args)
    {
        string body = args.Message.Body.ToString();

        logger.LogInformation("Received: {Body} from subscription.", body);

        // Complete the message. messages is deleted from the subscription.
        await args.CompleteMessageAsync(args.Message);
    }

    // Handle any errors when receiving messages
    Task ErrorHandler(ProcessErrorEventArgs args)
    {
        logger.LogError(args.Exception, "{Error}", args.Exception.Message);
        
        return Task.CompletedTask;
    }
}

在本機執行及測試應用程式

範例應用程式現在已準備好進行測試。確認提交至 API 的數據已傳送至 Azure Service Bus 主題，並由訂閱者背景工作服務取用：

按一下 [開始 偵錯] 按鈕或按 F5鍵以啟動 .NET.NET Aspire 專案。 .NET .NET Aspire 儀錶板應用程式應該會在瀏覽器中開啟。

選取 [開始 偵錯] 按鈕，或按 F5來啟動 .NET.NET Aspire 專案。 .NET .NET Aspire 儀錶板應用程式應該會在瀏覽器中開啟。

執行 dotnet run --project AspireSample.AppHost來啟動 .NET.NET Aspire 專案。 .NET .NET Aspire 儀錶板應用程式應該會在瀏覽器中開啟。

在 [資源] 頁面上的 [apiservice] 數據列中，尋找開啟 weatherforecast 端點的端點連結。記下 HTTPS 連接埠號碼。
在 .NET.NET Aspire 儀錶板上，導航至 aspiresample-workerservice 專案的日誌。
在終端機視窗中，使用 curl 命令將測試訊息傳送至 API：
```
curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire  
```
請務必將 {port} 替換成先前的埠號碼。
切換回 aspiresample-workerservice 記錄。您應該會看到輸出記錄中列印的測試訊息。

祝賀！您已建立並設定一個使用 Aspire 整合來連接到 Azure Service Bus 的 ASP.NET Core API。

清除資源

當您不再需要您所建立 Azure 資源時，請執行下列 Azure CLI 命令來刪除資源群組。刪除資源群組也會刪除其內含的資源。

az group delete --name <your-resource-group-name>

如需詳細資訊，請參閱在中的資源清理。

共用方式為