La AWS SDK per .NET V3 è entrata in modalità manutenzione.
[Ti consigliamo di migrare alla V4.AWS SDK per .NET](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html) Per ulteriori dettagli e informazioni su come eseguire la migrazione, consulta il nostro annuncio sulla modalità di [manutenzione](https://aws.amazon.com/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/).
Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# AWS Framework di elaborazione dei messaggi per.NET
Il AWS Message Processing Framework for .NET è un framework AWS nativo che semplifica lo sviluppo di applicazioni di elaborazione dei messaggi.NET che utilizzano AWS servizi come Amazon Simple Queue Service (SQS), Amazon Simple Notification Service (SNS) e Amazon. EventBridge Il framework riduce la quantità di codice standard che gli sviluppatori devono scrivere, consentendoti di concentrarti sulla logica aziendale durante la pubblicazione e l'utilizzo di messaggi. Per informazioni dettagliate su come il framework può semplificare lo sviluppo, consulta il post di blog [Introducing the AWS Message Processing Framework for .NET (](https://aws.amazon.com/blogs/developer/introducing-the-aws-message-processing-framework-for-net-preview/)Preview). La prima parte, in particolare, fornisce una dimostrazione che mostra la differenza tra l'utilizzo di chiamate API di basso livello e l'utilizzo del framework.
Il Message Processing Framework supporta le seguenti attività e funzionalità:
+ Invio di messaggi a SQS e pubblicazione di eventi su SNS e. EventBridge
+ Ricezione e gestione di messaggi da SQS utilizzando un poller a esecuzione prolungata, che viene in genere utilizzato nei servizi in background. Ciò include la gestione del timeout di visibilità durante la gestione di un messaggio per impedire ad altri client di elaborarlo.
+ Gestione dei messaggi nelle funzioni AWS Lambda .
+ Code FIFO (first-in-first-out) SQS e argomenti SNS.
+ OpenTelemetry per la registrazione.
Per dettagli su queste attività e funzionalità, consulta la sezione **Caratteristiche** del [post del blog](https://aws.amazon.com/blogs/developer/introducing-the-aws-message-processing-framework-for-net-preview/) e gli argomenti elencati di seguito.
Prima di iniziare, assicuratevi di aver [configurato l'ambiente e il progetto](net-dg-config.md). Consulta anche le informazioni contenute in[Funzionalità dell'SDK](net-dg-sdk-features.md).
**Altre risorse**
+ Il [https://www.nuget.org/packages/AWS.Messaging/](https://www.nuget.org/packages/AWS.Messaging/)pacchetto su [NuGet.org](https://www.nuget.org/).
+ Il [riferimento all'API](https://aws.github.io/aws-dotnet-messaging/).
+ Il `README` file nel GitHub repository all'indirizzo [https://github.com/aws/aws-dotnet-messaging/](https://github.com/aws/aws-dotnet-messaging/)
+ [Iniezione di dipendenze.NET](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection) da Microsoft.
+ [.NET Generic Host](https://learn.microsoft.com/en-us/dotnet/core/extensions/generic-host) di Microsoft.
**Topics**
+ [Inizia a usare](msg-proc-fw-get-started.md)
+ [Pubblica messaggi](msg-proc-fw-publish.md)
+ [Consuma messaggi](msg-proc-fw-consume.md)
+ [FIFO](msg-proc-fw-fifo.md)
+ [Registrazione e telemetria aperta](msg-proc-fw-telemetry.md)
+ [Personalizzazione](msg-proc-fw-customize.md)
+ [Sicurezza](msg-proc-fw-security.md)
# Inizia a usare il AWS Message Processing Framework per .NET
Prima di iniziare, assicurati di aver [configurato l'ambiente e il progetto](net-dg-config.md). Consulta anche le informazioni contenute in[Funzionalità dell'SDK](net-dg-sdk-features.md).
Questo argomento fornisce informazioni utili per iniziare a utilizzare il Message Processing Framework. Oltre alle informazioni sui prerequisiti e sulla configurazione, viene fornito un tutorial che mostra come implementare uno scenario comune.
## Prerequisiti e configurazione
+ Le credenziali fornite per l'applicazione devono disporre delle autorizzazioni appropriate per il servizio di messaggistica e le operazioni utilizzate. Per ulteriori informazioni, consulta gli argomenti sulla sicurezza per [SQS, [SNS](https://docs.aws.amazon.com/sns/latest/dg/security-iam.html)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-authentication-and-access-control.html) e [EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-iam.html)nelle rispettive guide per sviluppatori. [Consultate anche la parte del file [README](https://github.com/aws/aws-dotnet-messaging/) dedicata alle autorizzazioni GitHub specifiche.](https://github.com/aws/aws-dotnet-messaging/blob/main/README.md#permissions)
+ Per utilizzare il AWS Message Processing Framework per .NET, è necessario aggiungere il [https://www.nuget.org/packages/AWS.Messaging](https://www.nuget.org/packages/AWS.Messaging) NuGetpacchetto al progetto. Per esempio:
```
dotnet add package AWS.Messaging
```
+ Il framework si integra con il contenitore di [servizi di dependency injection (DI)](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection) di.NET. È possibile configurare il framework durante l'avvio dell'applicazione chiamando `AddAWSMessageBus` per aggiungerlo al contenitore 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("https://sqs.us-west-2.amazonaws.com/012345678910/MyAppProd");
});
```
## Tutorial
Questo tutorial dimostra come utilizzare il AWS Message Processing Framework per.NET. Crea due applicazioni: un'API ASP.NET Core Minimal che invia messaggi a una coda Amazon SQS quando riceve una richiesta su un endpoint API e un'applicazione console di lunga durata che esegue il polling di questi messaggi e li gestisce.
+ Le istruzioni di questo tutorial privilegiano l'interfaccia della riga di comando .NET, ma è possibile eseguire questo tutorial utilizzando strumenti multipiattaforma, come.NET CLI o Microsoft Visual Studio. Per informazioni sugli strumenti, consulta. [Installa e configura la tua toolchain](net-dg-dev-env.md)
+ Questo tutorial presuppone che tu stia utilizzando il tuo `[default]` profilo per le credenziali. Si presuppone inoltre che le credenziali a breve termine siano disponibili con le autorizzazioni appropriate per l'invio e la ricezione di messaggi Amazon SQS. [Per ulteriori informazioni, consulta gli argomenti sulla [Configura l'autenticazione SDK con AWS](creds-idc.md) sicurezza per SQS.](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-authentication-and-access-control.html)
**Nota**
Eseguendo questo tutorial, potresti incorrere in costi per la messaggistica SQS.
### Fasi
+ [Crea una coda SQS](#mpf-tutorial-queue)
+ [Crea ed esegui l'applicazione di pubblicazione](#mpf-tutorial-publish)
+ [Crea ed esegui l'applicazione di gestione](#mpf-tutorial-handle)
+ [Rimozione](#mpf-tutorial-cleanup)
### Crea una coda SQS
Questo tutorial richiede una coda SQS per inviare e ricevere messaggi. È possibile creare una coda utilizzando uno dei seguenti comandi per il o il AWS CLI . AWS Strumenti per PowerShell Prendi nota dell'URL della coda che viene restituito in modo da poterlo specificare nella configurazione del framework che segue.
------
#### [ AWS CLI ]
```
aws sqs create-queue --queue-name DemoQueue
```
------
#### [ AWS Strumenti per PowerShell ]
```
New-SQSQueue -QueueName DemoQueue
```
------
### Crea ed esegui l'applicazione di pubblicazione
Utilizzate la procedura seguente per creare ed eseguire l'applicazione di pubblicazione.
1. Aprire un prompt dei comandi o un terminale. Trovare o creare una cartella del sistema operativo in cui è possibile creare un progetto.NET.
1. In tale cartella, eseguire il seguente comando per creare il progetto.NET.
```
dotnet new webapi --name Publisher
```
1. Naviga nella cartella del nuovo progetto. Aggiungi una dipendenza dal AWS Message Processing Framework per .NET.
```
cd Publisher
dotnet add package AWS.Messaging
```
**Nota**
Se lo utilizzi AWS IAM Identity Center per l'autenticazione, assicurati di aggiungere anche `AWSSDK.SSO` e`AWSSDK.SSOOIDC`.
1. Sostituisci il codice `Program.cs` con il codice seguente.
```
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(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
{
///
/// Endpoint for posting a greeting message.
///
/// The greeting message.
/// The message publisher.
/// Async task result.
public static async Task 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
{
///
/// This class represents the message contents.
///
public class GreetingMessage
{
public string? SenderName { get; set; }
public string? Greeting { get; set; }
}
}
```
1. Esegui il comando seguente. Questo dovrebbe aprire una finestra del browser con l'interfaccia utente di Swagger, che ti permetterà di esplorare e testare la tua API.
```
dotnet watch run
```
1. Apri l'`/greeting`endpoint e scegli **Try** it out.
1. `senderName`Specificate `greeting` i valori per il messaggio e scegliete **Esegui**. Questo richiama la tua API, che invia il messaggio SQS.
### Crea ed esegui l'applicazione di gestione
Utilizzare la procedura seguente per creare ed eseguire l'applicazione di gestione.
1. Aprire un prompt dei comandi o un terminale. Trovare o creare una cartella del sistema operativo in cui è possibile creare un progetto.NET.
1. In tale cartella, eseguire il seguente comando per creare il progetto.NET.
```
dotnet new console --name Handler
```
1. Naviga nella cartella del nuovo progetto. Aggiungi una dipendenza dal AWS Message Processing Framework per .NET. Aggiungi anche il `Microsoft.Extensions.Hosting` pacchetto, che consente di configurare il framework tramite l'[host generico.NET](https://learn.microsoft.com/en-us/dotnet/core/extensions/generic-host).
```
cd Handler
dotnet add package AWS.Messaging
dotnet add package Microsoft.Extensions.Hosting
```
**Nota**
Se lo utilizzi AWS IAM Identity Center per l'autenticazione, assicurati di aggiungere anche `AWSSDK.SSO` e`AWSSDK.SSOOIDC`.
1. Sostituisci il codice `Program.cs` con il codice seguente.
```
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("greetingMessage");
}
// You can add additional message handlers here, using different message types.
});
});
var host = builder.Build();
await host.RunAsync();
namespace Handler
{
///
/// This class represents the message contents.
///
public class GreetingMessage
{
public string? SenderName { get; set; }
public string? Greeting { get; set; }
}
///
/// This handler is invoked each time you receive the message.
///
public class GreetingMessageHandler : IMessageHandler
{
public Task HandleAsync(
MessageEnvelope messageEnvelope,
CancellationToken token = default)
{
Console.WriteLine(
$"Received message {messageEnvelope.Message.Greeting} from {messageEnvelope.Message.SenderName}");
return Task.FromResult(MessageProcessStatus.Success());
}
}
}
```
1. Esegui il comando seguente. Questo avvia un sondaggio di lunga durata.
```
dotnet run
```
Poco dopo l'avvio, l'applicazione riceverà il messaggio inviato nella prima parte di questo tutorial e registrerà il seguente messaggio:
```
Received message {greeting} from {senderName}
```
1. Premi `Ctrl+C` per interrompere il sondaggio.
### Rimozione
Utilizzate uno dei seguenti comandi per AWS CLI o per AWS Strumenti per PowerShell eliminare la coda.
------
#### [ AWS CLI ]
```
aws sqs delete-queue --queue-url ""
```
------
#### [ AWS Strumenti per PowerShell ]
```
Remove-SQSQueue -QueueUrl ""
```
------
# Pubblica messaggi con il AWS Message Processing Framework per .NET
Il AWS Message Processing Framework for .NET supporta la pubblicazione di uno o più tipi di messaggi, l'elaborazione di uno o più tipi di messaggi o l'esecuzione di entrambe le operazioni nella stessa applicazione.
Il codice seguente mostra una configurazione per un'applicazione che pubblica tipi di messaggi diversi su AWS servizi diversi.
```
var builder = WebApplication.CreateBuilder(args);
// Register the AWS Message Processing Framework for .NET
builder.Services.AddAWSMessageBus(builder =>
{
// Register that you'll send messages of type ChatMessage to an existing queue
builder.AddSQSPublisher("https://sqs.us-west-2.amazonaws.com/012345678910/MyAppProd");
// Register that you'll publish messages of type OrderInfo to an existing SNS topic
builder.AddSNSPublisher("arn:aws:sns:us-west-2:012345678910:MyAppProd");
// Register that you'll publish messages of type FoodItem to an existing EventBridge bus
builder.AddEventBridgePublisher("arn:aws:events:us-west-2:012345678910:event-bus/default");
});
```
Dopo aver registrato il framework durante l'avvio, inserisci il generico `IMessagePublisher` nel tuo codice. Chiama il suo `PublishAsync` metodo per pubblicare uno qualsiasi dei tipi di messaggio configurati sopra. L'editore generico determinerà la destinazione verso cui indirizzare il messaggio in base al tipo.
Nell'esempio seguente, un controller ASP.NET MVC riceve sia `ChatMessage` messaggi che `OrderInfo` eventi dagli utenti, quindi li pubblica rispettivamente su Amazon SQS e Amazon SNS. Entrambi i tipi di messaggi possono essere pubblicati utilizzando l'editore generico configurato in precedenza.
```
[ApiController]
[Route("[controller]")]
public class PublisherController : ControllerBase
{
private readonly IMessagePublisher _messagePublisher;
public PublisherController(IMessagePublisher messagePublisher)
{
_messagePublisher = messagePublisher;
}
[HttpPost("chatmessage", Name = "Chat Message")]
public async Task PublishChatMessage([FromBody] ChatMessage message)
{
// Perform business and validation logic on the ChatMessage here.
if (message == null)
{
return BadRequest("A chat message was not submitted. Unable to forward to the message queue.");
}
if (string.IsNullOrEmpty(message.MessageDescription))
{
return BadRequest("The MessageDescription cannot be null or empty.");
}
// Send the ChatMessage to SQS, using the generic publisher.
await _messagePublisher.PublishAsync(message);
return Ok();
}
[HttpPost("order", Name = "Order")]
public async Task PublishOrder([FromBody] OrderInfo message)
{
if (message == null)
{
return BadRequest("An order was not submitted.");
}
// Publish the OrderInfo to SNS, using the generic publisher.
await _messagePublisher.PublishAsync(message);
return Ok();
}
}
```
Per indirizzare un messaggio alla logica di gestione appropriata, il framework utilizza dei metadati denominati *identificatori del tipo di messaggio*. Per impostazione predefinita, si tratta del nome completo del tipo.NET del messaggio, incluso il nome dell'assembly. Se inviate e gestite messaggi, questo meccanismo funziona bene se condividete la definizione degli oggetti del messaggio tra progetti. Tuttavia, se i messaggi vengono ridefiniti in diversi namespace o se state scambiando messaggi con altri framework o linguaggi di programmazione, potrebbe essere necessario sostituire l'identificatore del tipo di messaggio.
```
var builder = Host.CreateDefaultBuilder(args);
builder.ConfigureServices(services =>
{
// Register the AWS Message Processing Framework for .NET
services.AddAWSMessageBus(builder =>
{
// Register that you'll publish messages of type GreetingMessage to an existing queue
builder.AddSQSPublisher("https://sqs.us-west-2.amazonaws.com/012345678910/MyAppProd", "greetingMessage");
});
});
```
## Editori specifici per servizi
L'esempio mostrato sopra utilizza il formato generico`IMessagePublisher`, che può essere pubblicato su qualsiasi AWS servizio supportato in base al tipo di messaggio configurato. Il framework fornisce anche editori specifici per servizi per Amazon SQS, Amazon SNS e Amazon. EventBridge Questi editori specifici espongono opzioni che si applicano solo a quel servizio e che possono essere inserite utilizzando i tipi, e. `ISQSPublisher` `ISNSPublisher` `IEventBridgePublisher`
[Ad esempio, quando si inviano messaggi a una coda FIFO SQS, è necessario impostare l'ID del gruppo di messaggi appropriato.](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-key-terms.html) Il codice seguente mostra nuovamente l'`ChatMessage`esempio, ma ora viene utilizzato un `ISQSPublisher` per impostare opzioni specifiche di SQS.
```
public class PublisherController : ControllerBase
{
private readonly ISQSPublisher _sqsPublisher;
public PublisherController(ISQSPublisher sqsPublisher)
{
_sqsPublisher = sqsPublisher;
}
[HttpPost("chatmessage", Name = "Chat Message")]
public async Task PublishChatMessage([FromBody] ChatMessage message)
{
// Perform business and validation logic on the ChatMessage here
if (message == null)
{
return BadRequest("A chat message was not submitted. Unable to forward to the message queue.");
}
if (string.IsNullOrEmpty(message.MessageDescription))
{
return BadRequest("The MessageDescription cannot be null or empty.");
}
// Send the ChatMessage to SQS using the injected ISQSPublisher, with SQS-specific options
await _sqsPublisher.SendAsync(message, new SQSOptions
{
DelaySeconds = ,
MessageAttributes = ,
MessageDeduplicationId = ,
MessageGroupId =
});
return Ok();
}
}
```
Lo stesso può essere fatto per SNS e EventBridge, rispettivamente, utilizzando `ISNSPublisher` e. `IEventBridgePublisher`
```
await _snsPublisher.PublishAsync(message, new SNSOptions
{
Subject = ,
MessageAttributes = ,
MessageDeduplicationId = ,
MessageGroupId =
});
```
```
await _eventBridgePublisher.PublishAsync(message, new EventBridgeOptions
{
DetailType = ,
Resources = ,
Source = ,
Time =