第 4 版 (V4) 適用於 .NET 的 AWS SDK 已發行！

如需有關中斷變更和遷移應用程式的資訊，請參閱[遷移主題](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html)。

 [https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html)

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 開始使用適用於 .NET AWS 的訊息處理架構
<a name="msg-proc-fw-get-started"></a>

開始之前，請確定您已[設定環境](net-dg-config.md)並[設定專案](configuring-the-sdk.md)。也請檢閱 中的資訊[使用開發套件](net-dg-sdk-features.md)。

本主題提供的資訊可協助您開始使用訊息處理架構。除了先決條件和組態資訊之外，還提供教學課程，說明如何實作常見案例。

## 先決條件和組態
<a name="mpf-get-started-prereq"></a>
+ 您為應用程式提供的登入資料必須具有其使用的簡訊服務和操作的適當許可。如需詳細資訊，請參閱其各自開發人員指南中的 [SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-authentication-and-access-control.html)、[SNS](https://docs.aws.amazon.com/sns/latest/dg/security-iam.html) 和 [EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-iam.html) 的安全主題。另請參閱 GitHub 上討論特定[許可](https://github.com/aws/aws-dotnet-messaging/blob/main/README.md#permissions)的 [README](https://github.com/aws/aws-dotnet-messaging/) 檔案部分。
+ 若要使用適用於 .NET AWS 的訊息處理架構，您必須將 [https://www.nuget.org/packages/AWS.Messaging](https://www.nuget.org/packages/AWS.Messaging) NuGet 套件新增至您的專案。例如：

  ```
  dotnet add package AWS.Messaging
  ```
+ 框架與 .NET 的[相依性注入 (DI) 服務容器](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection)整合。您可以在應用程式啟動期間呼叫 `AddAWSMessageBus`以將其新增至 DI 容器，藉此設定架構。

  ```
  var builder = WebApplication.CreateBuilder(args);
  
  // Register the AWS Message Processing Framework for .NET
  builder.Services.AddAWSMessageBus(builder =>
  {
      // Register that you'll publish messages of type ChatMessage to an existing queue
      builder.AddSQSPublisher<ChatMessage>("https://sqs.us-west-2.amazonaws.com/012345678910/MyAppProd");
  });
  ```

## 教學課程
<a name="mpf-get-started-tutorial"></a>

本教學課程示範如何使用適用於 .NET AWS 的訊息處理架構。它會建立兩個應用程式：在 API 端點收到請求時將訊息傳送至 Amazon SQS 佇列的 ASP.NET Core Minimal API，以及輪詢這些訊息並加以處理的長時間執行主控台應用程式。
+ 本教學中的指示偏好 .NET CLI，但您可以使用 .NET CLI 或 Microsoft Visual Studio 等跨平台工具來執行本教學課程。如需工具的資訊，請參閱 [安裝和設定 的工具鏈 適用於 .NET 的 AWS SDK](net-dg-dev-env.md)。
+ 本教學假設您正在將`[default]`設定檔用於登入資料。它還假設短期憑證可用，並具有傳送和接收 Amazon SQS 訊息的適當許可。如需詳細資訊，請參閱 [適用於 .NET 的 AWS SDK 使用 驗證 AWS](creds-idc.md)和 [SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-authentication-and-access-control.html) 的安全主題。

**注意**  
透過執行本教學課程，您可能需要支付 SQS 訊息費用。

### 步驟
<a name="mpf-tutorial-steps"></a>
+ [建立 SQS 佇列](#mpf-tutorial-queue)
+ [建立並執行發佈應用程式](#mpf-tutorial-publish)
+ [建立並執行處理應用程式](#mpf-tutorial-handle)
+ [清除](#mpf-tutorial-cleanup)

### 建立 SQS 佇列
<a name="mpf-tutorial-queue"></a>

本教學課程需要 SQS 佇列來傳送訊息至 並從中接收訊息。您可以針對 AWS CLI 或 使用下列其中一個命令來建立佇列 AWS Tools for PowerShell。請記下傳回的佇列 URL，以便您可以在接下來的架構組態中指定該 URL。

------
#### [ AWS CLI ]

```
aws sqs create-queue --queue-name {{DemoQueue}}
```

------
#### [ AWS Tools for PowerShell ]

```
New-SQSQueue -QueueName DemoQueue
```

------

### 建立並執行發佈應用程式
<a name="mpf-tutorial-publish"></a>

使用下列程序來建立和執行發佈應用程式。

1. 開啟命令提示字元或終端機。尋找或建立可在其下建立 .NET 專案的作業系統資料夾。

1. 在該資料夾中，執行下列命令以建立 .NET 專案。

   ```
   dotnet new webapi --name Publisher
   ```

1. 導覽至新專案的資料夾。在適用於 .NET AWS 的訊息處理架構上新增相依性。

   ```
   cd Publisher
   dotnet add package AWS.Messaging
   ```
**注意**  
如果您使用 AWS IAM Identity Center 進行身分驗證，請務必同時新增 `AWSSDK.SSO`和 `AWSSDK.SSOOIDC`。

1. 使用`Program.cs`下列程式碼取代 中的程式碼。

   ```
   using AWS.Messaging;
   using Microsoft.AspNetCore.Mvc;
   using Publisher;
   
   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle.
   builder.Services.AddEndpointsApiExplorer();
   builder.Services.AddSwaggerGen();
   
   
   // Configure the AWS Message Processing Framework for .NET.
   builder.Services.AddAWSMessageBus(builder =>
   {
       // Check for input SQS URL.
       // The SQS URL should be passed as a command line argument or set in the Debug launch profile.
       if ((args.Length == 1) && (args[0].Contains("https://sqs.")))
       {
           // Register that you'll publish messages of type GreetingMessage:
           // 1. To a specified queue.
           // 2. Using the message identifier "greetingMessage", which will be used
           //    by handlers to route the message to the appropriate handler.
           builder.AddSQSPublisher<GreetingMessage>(args[0], "greetingMessage");
       }
       // You can map additional message types to queues or topics here as well.
   });
   var app = builder.Build();
   
   
   // Configure the HTTP request pipeline.
   if (app.Environment.IsDevelopment())
   {
       app.UseSwagger();
       app.UseSwaggerUI();
   }
   
   app.UseHttpsRedirection();
   
   // Create an API Endpoint that receives GreetingMessage objects
   // from the caller and then sends them as an SQS message.
   app.MapPost("/greeting", async ([FromServices] IMessagePublisher publisher, Publisher.GreetingMessage message) =>
       {
           return await PostGreeting(message, publisher);
       })
   .WithName("SendGreeting")
   .WithOpenApi();
   
   app.Run();
   
   public partial class Program
   {
       /// <summary>
       /// Endpoint for posting a greeting message.
       /// </summary>
       /// <param name="greetingMessage">The greeting message.</param>
       /// <param name="messagePublisher">The message publisher.</param>
       /// <returns>Async task result.</returns>
       public static async Task<IResult> PostGreeting(GreetingMessage greetingMessage,
           IMessagePublisher messagePublisher)
       {
           if (greetingMessage.SenderName == null || greetingMessage.Greeting == null)
           {
               return Results.BadRequest();
           }
   
           // Publish the message to the queue configured above.
           await messagePublisher.PublishAsync(greetingMessage);
   
           return Results.Ok();
       }
   }
   
   namespace Publisher
   {
       /// <summary>
       /// This class represents the message contents.
       /// </summary>
       public class GreetingMessage
       {
           public string? SenderName { get; set; }
           public string? Greeting { get; set; }
       }
   }
   ```

1. 執行下列命令。這應該會使用 Swagger UI 開啟瀏覽器視窗，讓您探索和測試 API。

   ```
   dotnet watch run {{<queue URL created earlier>}}
   ```

1. 開啟`/greeting`端點，然後選擇**試用**。

1. 指定訊息的 `senderName`和 `greeting`值，然後選擇**執行**。這會叫用您的 API，以傳送 SQS 訊息。

### 建立並執行處理應用程式
<a name="mpf-tutorial-handle"></a>

使用下列程序來建立和執行處理應用程式。

1. 開啟命令提示字元或終端機。尋找或建立可在其下建立 .NET 專案的作業系統資料夾。

1. 在該資料夾中，執行下列命令以建立 .NET 專案。

   ```
   dotnet new console --name Handler
   ```

1. 導覽至新專案的資料夾。在適用於 .NET AWS 的訊息處理架構上新增相依性。同時新增 `Microsoft.Extensions.Hosting`套件，可讓您透過 [.NET Generic Host](https://learn.microsoft.com/en-us/dotnet/core/extensions/generic-host) 設定架構。

   ```
   cd Handler
   dotnet add package AWS.Messaging
   dotnet add package Microsoft.Extensions.Hosting
   ```
**注意**  
如果您使用 AWS IAM Identity Center 進行身分驗證，請務必同時新增 `AWSSDK.SSO`和 `AWSSDK.SSOOIDC`。

1. 使用`Program.cs`下列程式碼取代 中的程式碼。

   ```
   using AWS.Messaging;
   using Handler;
   using Microsoft.Extensions.DependencyInjection;
   using Microsoft.Extensions.Hosting;
   
   var builder = Host.CreateDefaultBuilder(args);
   
   builder.ConfigureServices(services =>
   {
       // Register the AWS Message Processing Framework for .NET.
       services.AddAWSMessageBus(builder =>
       {
           // Check for input SQS URL.
           // The SQS URL should be passed as a command line argument or set in the Debug launch profile.
           if ((args.Length == 1) && (args[0].Contains("https://sqs.")))
           {
               // Register you'll poll the following queue.
               builder.AddSQSPoller(args[0]);
   
               // And that messages of type "greetingMessage" should be:
               // 1. Deserialized as GreetingMessage objects.
               // 2. Which are then passed to GreetingMessageHandler.
               builder.AddMessageHandler<GreetingMessageHandler, GreetingMessage>("greetingMessage");
   
           }
           // You can add additional message handlers here, using different message types. 
       });
   });
   
   var host = builder.Build();
   await host.RunAsync();
   
   namespace Handler
   {
       /// <summary>
       /// This class represents the message contents.
       /// </summary>
       public class GreetingMessage
       {
           public string? SenderName { get; set; }
           public string? Greeting { get; set; }
       }
   
       /// <summary>
       /// This handler is invoked each time you receive the message.
       /// </summary>
       public class GreetingMessageHandler : IMessageHandler<GreetingMessage>
       {
           public Task<MessageProcessStatus> HandleAsync(
               MessageEnvelope<GreetingMessage> messageEnvelope,
               CancellationToken token = default)
           {
               Console.WriteLine(
                   $"Received message {messageEnvelope.Message.Greeting} from {messageEnvelope.Message.SenderName}");
               return Task.FromResult(MessageProcessStatus.Success());
           }
       }
   }
   ```

1. 執行下列命令。這會啟動長時間執行的輪詢器。

   ```
   dotnet run {{<queue URL created earlier>}}
   ```

   啟動後，應用程式很快就會收到本教學課程第一部分所傳送的訊息，並記錄下列訊息：

   ```
   Received message {greeting} from {senderName}
   ```

1. 按 `Ctrl+C` 停止輪詢器。

### 清除
<a name="mpf-tutorial-cleanup"></a>

使用下列其中一個命令，讓 AWS CLI 或 AWS Tools for PowerShell 刪除佇列。

------
#### [ AWS CLI ]

```
aws sqs delete-queue --queue-url "{{<queue URL created earlier>}}"
```

------
#### [ AWS Tools for PowerShell ]

```
Remove-SQSQueue -QueueUrl "{{<queue URL created earlier>}}"
```

------