Condividi tramite


Guida introduttiva: Inviare e ricevere eventi da Hub eventi di Azure tramite .NET

In questa guida introduttiva si apprenderà come inviare eventi a un hub eventi e quindi ricevere tali eventi dall'hub eventi usando la libreria .NET Azure.Messaging.EventHubs .

Nota

Le guide di avvio rapido consentono di aumentare rapidamente il servizio. Se si ha già familiarità con il servizio, è possibile visualizzare esempi .NET per Hub eventi nel repository .NET SDK in GitHub: esempi di Hub eventi in GitHub, esempi del processore di eventi in GitHub.

Prerequisiti

Se non si ha familiarità con Hub eventi di Azure, vedere Panoramica di Hub eventi prima di seguire questa guida introduttiva.

Per completare questa guida introduttiva è necessario soddisfare i prerequisiti seguenti:

  • Sottoscrizione di Microsoft Azure. Per usare i servizi di Azure, tra cui Hub eventi di Azure, è necessaria una sottoscrizione. Se non si ha un account Azure, è possibile iscriversi per ottenere una versione di valutazione gratuita oppure usare i vantaggi della sottoscrizione di MSDN per la creazione di un account.
  • Microsoft Visual Studio 2022. La libreria client di Hub eventi di Azure usa le nuove funzionalità introdotte in C# 8.0. È comunque possibile usare la libreria con le versioni precedenti del linguaggio C#, ma la nuova sintassi non sarà disponibile. Per usare la sintassi completa, è consigliabile compilare con .NET Core SDK 3.0 o versione successiva e la versione del linguaggio impostata su latest. Se si usa Visual Studio, le versioni precedenti a Visual Studio 2022 non sono compatibili con gli strumenti necessari per compilare progetti C# 8.0. Visual Studio 2022, inclusa l'edizione Community gratuita, può essere scaricato qui.
  • Creare uno spazio dei nomi di Hub eventi e un hub eventi. Il primo passaggio consiste nell'usare il portale di Azure per creare uno spazio dei nomi di Hub eventi e un hub eventi nello spazio dei nomi . Ottenere quindi le credenziali di gestione necessarie all'applicazione per comunicare con l'hub eventi. Per creare uno spazio dei nomi e un hub eventi, vedere Avvio rapido: Creare un hub eventi usando portale di Azure.

Autenticare l'app in Azure

Questa guida introduttiva illustra due modi per connettersi a Hub eventi di Azure:

  • Senza password (autenticazione di Microsoft Entra)
  • Connection string

La prima opzione illustra come usare l'entità di sicurezza in Azure Active Directory e il controllo degli accessi in base al ruolo per connettersi a uno spazio dei nomi di Hub eventi. Non è necessario preoccuparsi di avere stringa di connessione hardcoded nel codice o in un file di configurazione o in un'archiviazione sicura come Azure Key Vault.

La seconda opzione mostra come usare un stringa di connessione per connettersi a uno spazio dei nomi di Hub eventi. Se non si ha familiarità con Azure, è possibile trovare l'opzione stringa di connessione più semplice da seguire. È consigliabile usare l'opzione senza password in applicazioni e ambienti di produzione reali. Per altre informazioni, consultare Autenticazione e autorizzazione. Per altre informazioni sull'autenticazione senza password, vedere la pagina di panoramica.

Assegnare ruoli all'utente di Microsoft Entra

Quando si sviluppa in locale, assicurarsi che l'account utente che si connette a Hub eventi di Azure disponga delle autorizzazioni corrette. Per inviare e ricevere messaggi, è necessario il ruolo di proprietario dei dati Hub eventi di Azure. Per assegnare a se stessi questo ruolo, è necessario il ruolo Accesso utente Amministrazione istrator o un altro ruolo che include l'azioneMicrosoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo sono disponibili nella pagina panoramica dell'ambito .

L'esempio seguente assegna il Azure Event Hubs Data Owner ruolo all'account utente, che fornisce l'accesso completo alle risorse di Hub eventi di Azure. In uno scenario reale, seguire il principio dei privilegi minimi per concedere agli utenti solo le autorizzazioni minime necessarie per un ambiente di produzione più sicuro.

Ruoli predefiniti di Azure per Hub eventi di Azure

Per Hub eventi di Azure, la gestione degli spazi dei nomi e di tutte le risorse correlate tramite il portale di Azure e l'API di gestione delle risorse di Azure è già protetta usando il modello di controllo degli accessi in base al ruolo di Azure. Azure offre i ruoli predefiniti di Azure seguenti per autorizzare l'accesso a uno spazio dei nomi di Hub eventi:

  • Hub eventi di Azure Proprietario dati: consente l'accesso ai dati allo spazio dei nomi di Hub eventi e alle relative entità (code, argomenti, sottoscrizioni e filtri)
  • Hub eventi di Azure Mittente dati: usare questo ruolo per concedere al mittente l'accesso allo spazio dei nomi di Hub eventi e alle relative entità.
  • Hub eventi di Azure Ricevitore dati: usare questo ruolo per concedere al ricevitore l'accesso allo spazio dei nomi di Hub eventi e alle relative entità.

Per creare un ruolo personalizzato, vedere Diritti necessari per le operazioni di Hub eventi.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà un minuto o due. In rari casi, possono essere necessari fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nella portale di Azure individuare lo spazio dei nomi di Hub eventi usando la barra di ricerca principale o lo spostamento a sinistra.

  2. Nella pagina di panoramica selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM), selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

    Screenshot che mostra come assegnare un ruolo.

  5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Azure Event Hubs Data Owner e selezionare il risultato corrispondente. Scegliere quindi Avanti.

  6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain) e quindi scegliere Selezionare nella parte inferiore della finestra di dialogo.

  8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi Rivedi e assegna di nuovo per completare il processo.

Avviare Visual Studio e accedere ad Azure

È possibile autorizzare l'accesso allo spazio dei nomi del bus di servizio seguendo questa procedura:

  1. Avviare Visual Studio. Se viene visualizzata la finestra Attività iniziali , selezionare il collegamento Continua senza codice nel riquadro destro.

  2. Selezionare il pulsante Accedi in alto a destra in Visual Studio.

    Screenshot che mostra un pulsante per accedere ad Azure con Visual Studio.

  3. Accedere usando l'account Microsoft Entra a cui è stato assegnato un ruolo in precedenza.

    Screenshot che mostra la selezione dell'account.

Inviare eventi all'hub eventi

Questa sezione illustra come creare un'applicazione console .NET Core per inviare eventi all'hub eventi creato.

Creare un'applicazione console

  1. Se Visual Studio 2022 è già aperto, selezionare File dal menu, selezionare Nuovo e quindi Progetto. In caso contrario, avviare Visual Studio 2022 e selezionare Crea un nuovo progetto se viene visualizzata una finestra popup.

  2. Nella finestra di dialogo Crea un nuovo progetto seguire questa procedura: se non viene visualizzata questa finestra di dialogo, selezionare File dal menu, selezionare Nuovoe quindi selezionare Progetto.

    1. Selezionare C# come linguaggio di programmazione.

    2. Selezionare Console come tipo di applicazione.

    3. Selezionare Applicazione console nell'elenco dei risultati.

    4. Quindi seleziona Avanti.

      Immagine che mostra la finestra di dialogo Nuovo progetto

  3. Immettere EventHubsSender come nome del progetto, EventHubsQuickStart per il nome della soluzione e quindi selezionare Avanti.

    Immagine che mostra la pagina in cui immettere i nomi di soluzione e progetto

  4. Nella pagina Informazioni aggiuntive selezionare Crea.

Aggiungere i pacchetti NuGet al progetto

  1. Scegliere Strumenti>Gestione pacchetti NuGet>Console di Gestione pacchetti dal menu.

  2. Eseguire i comandi seguenti per installare i pacchetti NuGet Azure.Messaging.EventHubs e Azure.Identity . Premere INVIO per eseguire il secondo comando.

    Install-Package Azure.Messaging.EventHubs
    Install-Package Azure.Identity
    

Scrivere codice per inviare eventi all'hub eventi

  1. Sostituire il codice esistente nel Program.cs file con il codice di esempio seguente. Sostituire quindi e <HUB_NAME> impostare <EVENT_HUB_NAMESPACE> i valori segnaposto per i EventHubProducerClient parametri con i nomi dello spazio dei nomi di Hub eventi e dell'hub eventi. Ad esempio: "spehubns0309.servicebus.windows.net" e "spehub".

    Ecco i passaggi importanti del codice:

    1. Crea un oggetto EventHubProducerClient usando lo spazio dei nomi e il nome dell'hub eventi.
    2. Richiama il metodo CreateBatchAsync nell'oggetto EventHubProducerClient per creare un oggetto EventDataBatch .
    3. Aggiungere eventi al batch usando il metodo EventDataBatch.TryAdd .
    4. Invia il batch di messaggi all'hub eventi usando il metodo EventHubProducerClient.SendAsync .
    using Azure.Identity;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Producer;
    using System.Text;
    
    // number of events to be sent to the event hub
    int numOfEvents = 3;
    
    // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
    // of the application, which is best practice when events are being published or read regularly.
    // TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
    EventHubProducerClient producerClient = new EventHubProducerClient(
        "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
        "<HUB_NAME>",
        new DefaultAzureCredential());
    
    // Create a batch of events 
    using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();
    
    for (int i = 1; i <= numOfEvents; i++)
    {
        if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
        {
            // if it is too large for the batch
            throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
        }
    }
    
    try
    {
        // Use the producer client to send the batch of events to the event hub
        await producerClient.SendAsync(eventBatch);
        Console.WriteLine($"A batch of {numOfEvents} events has been published.");
        Console.ReadLine();
    }
    finally
    {
        await producerClient.DisposeAsync();
    }
    
  1. Compilare il progetto e assicurarsi che non siano presenti errori.

  2. Eseguire il programma e attendere il messaggio di conferma.

    A batch of 3 events has been published.
    

    Importante

    Se si usa l'autenticazione basata su Controllo di accesso ruoli di Azure Active Directory (Senza password), selezionare Strumenti e quindi opzioni. Nella finestra Opzioni espandere Autenticazione del servizio di Azure e selezionare Selezione account. Verificare di usare l'account aggiunto al ruolo proprietario dati Hub eventi di Azure nello spazio dei nomi di Hub eventi.

  3. Nella pagina Spazio dei nomi di Hub eventi nella portale di Azure vengono visualizzati tre messaggi in arrivo nel grafico Messaggi. Aggiornare la pagina per aggiornare il grafico, se necessario. La conferma che i messaggi sono stati ricevuti potrebbe comparire dopo alcuni secondi.

    Immagine della pagina portale di Azure per verificare che l'hub eventi abbia ricevuto gli eventi

    Nota

    Per il codice sorgente completo con commenti più informativi, vedere questo file in GitHub

Ricevere eventi dall'hub eventi

Questa sezione illustra come scrivere un'applicazione console .NET Core che riceve eventi da un hub eventi usando un processore di eventi. Il processore di eventi semplifica la ricezione di eventi da hub eventi.

Creare un account Archiviazione di Azure e un contenitore BLOB

In questo argomento di avvio rapido si usa una risorsa di archiviazione di Azure come archivio di checkpoint. Seguire questa procedura per creare un account di archiviazione di Azure.

  1. Creare un account di archiviazione di Azure
  2. Creare un contenitore BLOB
  3. Eseguire l'autenticazione nel contenitore BLOB usando l'autenticazione dell'ID Entra (senza password) o un stringa di connessione allo spazio dei nomi .

Seguire questi consigli quando si usa Archiviazione BLOB di Azure come archivio checkpoint:

  • Usare un contenitore separato per ogni gruppo di consumer. È possibile usare lo stesso account di archiviazione, ma usare un contenitore per ogni gruppo.
  • Non usare il contenitore per altri elementi e non usare l'account di archiviazione per altri elementi.
  • Archiviazione account deve trovarsi nella stessa area in cui si trova l'applicazione distribuita. Se l'applicazione è locale, provare a scegliere l'area più vicina possibile.

Nella pagina Archiviazione account della portale di Azure, nella sezione Servizio BLOB verificare che le impostazioni seguenti siano disabilitate.

  • Spazio dei nomi gerarchico
  • Eliminazione temporanea dei BLOB
  • Controllo delle versioni

Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati BLOB disponga delle autorizzazioni corrette. È necessario Archiviazione Collaboratore ai dati BLOB per leggere e scrivere dati BLOB. Per assegnare a se stessi questo ruolo, è necessario assegnare il ruolo Amministratore accesso utenti o un altro ruolo che include l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere la pagina di panoramica dell'ambito.

In questo scenario si assegneranno le autorizzazioni all'account utente, con ambito all'account di archiviazione, per seguire il principio dei privilegi minimi. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente assegnerà il ruolo collaboratore ai dati BLOB Archiviazione all'account utente, che fornisce sia l'accesso in lettura che in scrittura ai dati BLOB nell'account di archiviazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nella portale di Azure individuare l'account di archiviazione usando la barra di ricerca principale o lo spostamento a sinistra.

  2. Nella pagina di panoramica dell'account di archiviazione selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM), selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

    Screenshot che mostra come assegnare un ruolo dell'account di archiviazione.

  5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Archiviazione Collaboratore dati BLOB e selezionare il risultato corrispondente e quindi scegliere Avanti.

  6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain) e quindi scegliere Selezionare nella parte inferiore della finestra di dialogo.

  8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi Rivedi e assegna di nuovo per completare il processo.

Creare un progetto per l'app ricevente

  1. Nella finestra Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione EventHubQuickStart, scegliere Aggiunti e selezionare Nuovo progetto.
  2. Selezionare Applicazione console e selezionare Avanti.
  3. Immettere EventHubsReceiver per Nome progetto e selezionare Crea.
  4. Nella finestra Esplora soluzioni fare clic con il pulsante destro del mouse su EventHubsReceiver e scegliere Imposta come progetto di avvio.

Aggiungere i pacchetti NuGet al progetto

  1. Scegliere Strumenti>Gestione pacchetti NuGet>Console di Gestione pacchetti dal menu.

  2. Nella finestra della console di Gestione pacchetti verificare che EventHubsReceiver sia selezionato per il progetto predefinito. In caso contrario, usare l'elenco a discesa per selezionare EventHubsReceiver.

  3. Eseguire il comando seguente per installare i pacchetti Azure.Messaging.EventHubs e Azure.Identity NuGet. Premere INVIO per eseguire l'ultimo comando.

    Install-Package Azure.Messaging.EventHubs
    Install-Package Azure.Messaging.EventHubs.Processor
    Install-Package Azure.Identity
    

Aggiornare il codice

Sostituire il contenuto di Program.cs con il codice seguente:

  1. Sostituire il codice esistente nel Program.cs file con il codice di esempio seguente. Sostituire quindi i <STORAGE_ACCOUNT_NAME> valori segnaposto e <BLOB_CONTAINER_NAME> per l'URI BlobContainerClient . Sostituire anche i <EVENT_HUB_NAMESPACE> valori segnaposto e <HUB_NAME> .EventProcessorClient

    Ecco i passaggi importanti del codice:

    1. Crea un oggetto EventProcessorClient usando lo spazio dei nomi di Hub eventi e il nome dell'hub eventi. È necessario compilare l'oggetto BlobContainerClient per il contenitore nell'archiviazione di Azure creata in precedenza.
    2. Specifica i gestori per gli eventi ProcessEventAsync e ProcessErrorAsync dell'oggetto EventProcessorClient .
    3. Avvia l'elaborazione degli eventi richiamando StartProcessingAsync nell'oggetto EventProcessorClient .
    4. Arresta l'elaborazione degli eventi dopo 30 secondi richiamando StopProcessingAsync nell'oggetto EventProcessorClient .
    using Azure.Identity;
    using Azure.Messaging.EventHubs;
    using Azure.Messaging.EventHubs.Consumer;
    using Azure.Messaging.EventHubs.Processor;
    using Azure.Storage.Blobs;
    using System.Text;
    
    // Create a blob container client that the event processor will use
    // TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTATINAER_NAME> with actual names
    BlobContainerClient storageClient = new BlobContainerClient(
        new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net/<BLOB_CONTAINER_NAME>"),
        new DefaultAzureCredential());
    
    // Create an event processor client to process events in the event hub
    // TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
    var processor = new EventProcessorClient(
        storageClient,
        EventHubConsumerClient.DefaultConsumerGroupName,
        "<EVENT_HUB_NAMESPACE>.servicebus.windows.net",
        "<HUB_NAME>",
        new DefaultAzureCredential());
    
    // Register handlers for processing events and handling errors
    processor.ProcessEventAsync += ProcessEventHandler;
    processor.ProcessErrorAsync += ProcessErrorHandler;
    
    // Start the processing
    await processor.StartProcessingAsync();
    
    // Wait for 30 seconds for the events to be processed
    await Task.Delay(TimeSpan.FromSeconds(30));
    
    // Stop the processing
    await processor.StopProcessingAsync();
    
    Task ProcessEventHandler(ProcessEventArgs eventArgs)
    {
        // Write the body of the event to the console window
        Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
        Console.ReadLine();
        return Task.CompletedTask;
    }
    
    Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
    {
        // Write details about the error to the console window
        Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
        Console.WriteLine(eventArgs.Exception.Message);
        Console.ReadLine();
        return Task.CompletedTask;
    }
    
  1. Compilare il progetto e assicurarsi che non siano presenti errori.

    Nota

    Per il codice sorgente completo con commenti più informativi, vedere questo file in GitHub.

  2. Eseguire l'applicazione ricevente.

  3. Verrà visualizzato un messaggio che informa che gli eventi sono stati ricevuti. Premere INVIO dopo aver visualizzato un messaggio di evento ricevuto.

    Received event: Event 1
    Received event: Event 2
    Received event: Event 3    
    

    Questi eventi sono i tre eventi inviati in precedenza all'hub eventi eseguendo il programma mittente.

  4. Nella portale di Azure è possibile verificare che siano presenti tre messaggi in uscita inviati a Hub eventi all'applicazione ricevente. Aggiornare la pagina per aggiornare il grafico. La conferma che i messaggi sono stati ricevuti potrebbe comparire dopo alcuni secondi.

    Immagine della pagina portale di Azure per verificare che l'hub eventi abbia inviato eventi all'app ricevente

Convalida dello schema per applicazioni basate su Hub eventi SDK

È possibile usare Registro schemi di Azure per eseguire la convalida dello schema quando si trasmetteno dati con le applicazioni basate su SDK di Hub eventi. Registro schemi di Azure di Hub eventi offre un repository centralizzato per la gestione degli schemi ed è possibile connettere facilmente le applicazioni nuove o esistenti al Registro schemi.

Per altre informazioni, vedere Convalidare gli schemi con Hub eventi SDK.

Esempi e informazioni di riferimento

Questa guida introduttiva fornisce istruzioni dettagliate per implementare uno scenario di invio di un batch di eventi a un hub eventi e quindi di riceverli. Per altri esempi, selezionare i collegamenti seguenti.

Per informazioni di riferimento complete sulla libreria .NET, vedere la documentazione dell'SDK.

Pulire le risorse

Eliminare il gruppo di risorse con lo spazio dei nomi di Hub eventi o eliminare solo lo spazio dei nomi se si vuole mantenere il gruppo di risorse.

Vedere l'esercitazione seguente: