Delen via


Integratie van .NET AspireAzure Queue Storage

omvat:hostingintegratie en Client integratie

Azure Queue Storage- is een service voor het opslaan van grote aantallen berichten die overal ter wereld toegankelijk zijn via geverifieerde aanroepen. Met de integratie van .NET AspireAzure Queue Storage kunt u verbinding maken met bestaande Azure Queue Storage-exemplaren of nieuwe exemplaren maken vanuit .NET toepassingen.

Hostingintegratie

De .NET.NET AspireAzure Storage hosting integratiemodellen de verschillende opslagbronnen als de volgende typen:

Als u toegang wilt krijgen tot deze typen en API's om ze uit te drukken, voeg dan het 📦Aspire.Hosting.Azure.Storage NuGet-pakket toe in het app-host project.

dotnet add package Aspire.Hosting.Azure.Storage

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Azure Storage-resource toevoegen

Roep in uw app-hostproject AddAzureStorage aan om een Azure Storage-resourcebouwer toe te voegen en te retourneren.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage");

// An Azure Storage resource is required to add any of the following:
//
// - Azure Blob storage resource.
// - Azure Queue storage resource.
// - Azure Table storage resource.

// After adding all resources, run the app...

Wanneer u een AzureStorageResource toevoegt aan de app-host, worden er andere nuttige API's weergegeven om Azure Blob-, Queue- en Table Storage-resources toe te voegen. Met andere woorden, u moet een AzureStorageResource toevoegen voordat u een van de andere opslagbronnen toevoegt.

Belangrijk

Wanneer u AddAzureStorageaanroept, wordt impliciet AddAzureProvisioningaangeroepen. Hiermee wordt ondersteuning toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de app. De app moet het juiste abonnement en de juiste locatie configureren. Zie Lokale inrichting: Configuratievoor meer informatie.

Gegenereerde voorziening Bicep

Als je nieuw bent met Bicep, is dit een domeinspecifieke taal voor het definiëren van Azure-bronnen. Met .NET.NET Aspirehoeft u bicep niet handmatig te schrijven, in plaats daarvan genereren de inrichtings-API's Bicep voor u. Wanneer u uw app publiceert, wordt de gegenereerde Bicep uitgegeven naast het manifestbestand. Wanneer u een Azure Storage-resource toevoegt, wordt de volgende Bicep gegenereerd:


schakelen Azure Storage Bicep.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalType string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: take('storage${uniqueString(resourceGroup().id)}', 24)
  kind: 'StorageV2'
  location: location
  sku: {
    name: 'Standard_GRS'
  }
  properties: {
    accessTier: 'Hot'
    allowSharedKeyAccess: false
    minimumTlsVersion: 'TLS1_2'
    networkAcls: {
      defaultAction: 'Allow'
    }
  }
  tags: {
    'aspire-resource-name': 'storage'
  }
}

resource blobs 'Microsoft.Storage/storageAccounts/blobServices@2024-01-01' = {
  name: 'default'
  parent: storage
}

resource storage_StorageBlobDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageTableDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageQueueDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88')
    principalType: principalType
  }
  scope: storage
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

De voorgaande Bicep is een module die een Azure Storage-account in richt met de volgende standaardwaarden:

  • kind: het type opslagaccount. De standaardwaarde is StorageV2.
  • sku: de SKU van het opslagaccount. De standaardwaarde is Standard_GRS.
  • properties: de eigenschappen van het opslagaccount:
    • accessTier: de toegangslaag van het opslagaccount. De standaardwaarde is Hot.
    • allowSharedKeyAccess: een Booleaanse waarde die aangeeft of het opslagaccount toestaat dat aanvragen worden geautoriseerd met de toegangssleutel voor het account. De standaardwaarde is false.
    • minimumTlsVersion: de minimaal ondersteunde TLS-versie voor het opslagaccount. De standaardwaarde is TLS1_2.
    • networkAcls: de netwerk-ACL's voor het opslagaccount. De standaardwaarde is { defaultAction: 'Allow' }.

Naast het opslagaccount wordt ook een blobcontainer geleverd.

De volgende roltoewijzingen worden toegevoegd aan het opslagaccount om uw toepassing toegang te verlenen. Zie de ingebouwde ingebouwde rollen voor Azure op rollen gebaseerd toegangsbeheer (Azure RBAC) voor meer informatie:

Rol/id Beschrijving
Inzender voor opslagblobgegevens
ba92f5b4-2d11-453d-a403-e96b0029c9fe
Lees-, schrijf- en verwijder Azure Storage-containers en -blobs.
Inzender voor opslagtabelgegevens
0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3
Lees-, schrijf- en verwijder Azure Storage-tabellen en -entiteiten.
Inzender voor opslagwachtrijgegevens
974c5e8b-45b9-4653-ba55-5f855dd0fb88
Lees-, schrijf- en verwijder Azure Storage-wachtrijen en wachtrijberichten.

De gegenereerde Bicep is een uitgangspunt en kan worden aangepast aan uw specifieke vereisten.

Voorzieninginfrastructuur aanpassen

Alle .NET AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep aanpassen door een vloeiende API te bieden waarmee u de Azure-resources kunt configureren, met behulp van de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. U kunt bijvoorbeeld de kind, sku, propertiesen meer configureren. In het volgende voorbeeld ziet u hoe u de Azure Storage-resource aanpast:

builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var storageAccount = infra.GetProvisionableResources()
                                  .OfType<StorageAccount>()
                                  .Single();

        storageAccount.AccessTier = StorageAccountAccessTier.Cool;
        storageAccount.Sku = new StorageSku { Name = StorageSkuName.PremiumZrs };
        storageAccount.Tags.Add("ExampleKey", "Example value");
    });

De voorgaande code:

Er zijn nog veel meer configuratieopties beschikbaar om de Azure Storage-resource aan te passen. Zie Azure.Provisioning.Storagevoor meer informatie.

Verbinding maken met een bestaand Azure Storage-account

Mogelijk hebt u een bestaand Azure Storage-account waarmee u verbinding wilt maken. In plaats van een nieuwe Azure Storage-resource weer te geven, kunt u een verbindingsreeks toevoegen aan de app-host. Als u een verbinding wilt toevoegen aan een bestaand Azure Storage-account, roept u de methode AddConnectionString aan:

var builder = DistributedApplication.CreateBuilder(args);

var blobs = builder.AddConnectionString("blobs");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(blobs);

// After adding all resources, run the app...

Notitie

Verbindingsreeksen worden gebruikt om een breed scala aan verbindingsgegevens weer te geven, waaronder databaseverbindingen, berichtbrokers, eindpunt-URI's en andere services. In .NET.NET Aspire nomenclatuur wordt de term "verbindingsreeks" gebruikt om alle soorten verbindingsgegevens weer te geven.

De verbindingsreeks is geconfigureerd in de configuratie van de app-host, meestal onder gebruikersgeheimen, onder de sectie ConnectionStrings. De app-host injecteert deze verbindingsreeks als een omgevingsvariabele in alle afhankelijke resources, bijvoorbeeld:

{
    "ConnectionStrings": {
        "blobs": "https://{account_name}.blob.core.windows.net/"
    }
}

De afhankelijke resource heeft toegang tot de geïnjecteerde verbindingsreeks door de methode GetConnectionString aan te roepen en de verbindingsnaam door te geven als de parameter, in dit geval "blobs". De GetConnectionString-API is een afkorting voor IConfiguration.GetSection("ConnectionStrings")[name].

Resource voor Azure Storage-emulator toevoegen

Als u een Azure Storage-emulatorresource wilt toevoegen, koppelt u een aanroep op een IResourceBuilder<AzureStorageResource> aan de RunAsEmulator-API:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage")
                     .RunAsEmulator();

// After adding all resources, run the app...

Wanneer u RunAsEmulatoraanroept, worden uw opslagbronnen geconfigureerd voor lokaal uitvoeren met behulp van een emulator. De emulator in dit geval is Azurite. De opensource-emulator Van Azurite biedt een gratis lokale omgeving voor het testen van uw Azure Blob-, Queue Storage- en Table Storage-apps en het is een perfecte aanvulling op de .NET AspireAzure hostingintegratie. Azurite is niet geïnstalleerd, maar is toegankelijk voor .NET.NET Aspire als container. Wanneer u een container toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de afbeelding mcr.microsoft.com/azure-storage/azurite, wordt de container gemaakt en gestart zodra de app-host wordt gestart. Zie levenscyclus van containerresourcesvoor meer informatie.

Azurite-container configureren

Er zijn verschillende configuraties beschikbaar voor containerresources. U kunt bijvoorbeeld de poorten van de container, omgevingsvariabelen, de levensduuren meer configureren.

Azurite-containerpoorten configureren

De Azurite-container stelt standaard, wanneer deze is geconfigureerd door .NET.NET Aspire, de volgende eindpunten bloot:

Eindpunt Containerpoort Host-poort
blob 10.000 dynamisch
queue 10001 dynamisch
table 10002 dynamisch

De poort waarop ze luisteren, is standaard dynamisch. Wanneer de container wordt gestart, worden de poorten toegewezen aan een willekeurige poort op de hostcomputer. Als u de eindpuntpoorten wilt configureren, maakt u kettingaanroepen op de containerresourcebouwer die wordt geleverd door de RunAsEmulator Methode, zoals in het volgende voorbeeld:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithBlobPort("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 27002);
                     });

// After adding all resources, run the app...

De voorgaande code configureert de bestaande blob, queueen table eindpunten van de Azurite-container om respectievelijk te luisteren op poorten 27000, 27001en 27002. De poorten van de Azurite-container worden toegewezen aan de hostpoorten, zoals wordt weergegeven in de volgende tabel:

Eindpuntnaam Poorttoewijzing (container:host)
blob 10000:27000
queue 10001:27001
table 10002:27002
Azurite-container configureren met een permanente levensduur

Als u de Azurite-container met een permanente levensduur wilt configureren, roept u de methode WithLifetime op de Resource van de Azurite-container aan en geeft u ContainerLifetime.Persistentdoor:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithLifetime(ContainerLifetime.Persistent);
                     });

// After adding all resources, run the app...

Zie Levensduur van containerresourcesvoor meer informatie.

Azurite-container configureren met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de resource van de Azure Storage-emulator, roept u de WithDataVolume methode aan op de resource van de Azure Storage-emulator:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataVolume();
                     });

// After adding all resources, run the app...

Het gegevensvolume wordt gebruikt om de Azurite-gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /data pad in de Azure-container en wanneer er geen name parameter wordt opgegeven, wordt de naam opgemaakt als .azurite/{resource name}. Voor meer informatie over gegevensvolumes en details over waarom men de voorkeur geeft aan gegevensvolumes boven koppelingen, zie Docker docs: Volumes.

Azurite-container configureren met datakoppeling

Als u een koppeling voor gegevensbinding wilt toevoegen aan de resource van de Azure Storage-emulator, roept u de WithDataBindMount methode aan:

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataBindMount("../Azurite/Data");
                     });

// After adding all resources, run the app...

Belangrijk

Data bind mounts hebben beperkte functionaliteit vergeleken met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bind-mounts bieden echter directe toegang tot en wijziging van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waar wijzigingen in realtime nodig zijn.

Gegevensbindkoppelingen zijn afhankelijk van het bestandssysteem van de hostcomputer om de Azurite-gegevens bij herstarts van de container te behouden. De koppeling van de gegevensbinding wordt gekoppeld aan het ../Azurite/Data pad op de hostcomputer ten opzichte van de app-hostmap (IDistributedApplicationBuilder.AppHostDirectory) in de Azure-container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

Verbinding maken met opslagbronnen

Wanneer de .NET.NET Aspire app-host wordt uitgevoerd, kunnen de opslagbronnen worden geopend door externe hulpprogramma's, zoals de Azure Storage Explorer-. Als uw opslagresource lokaal wordt uitgevoerd met behulp van Azurite, wordt deze automatisch opgehaald door de Azure Storage Explorer.

Notitie

De Azure Storage Explorer detecteert Opslagbronnen van Azurite, ervan uitgaande dat de standaardpoorten worden gebruikt. Als u de Azurite-container hebt geconfigureerd om verschillende poorten te gebruiken, moet u de Azure Storage Explorer configureren om verbinding te maken met de juiste poorten.

Voer de volgende stappen uit om vanuit Azure Storage Explorer verbinding te maken met de opslagresource:

  1. Voer de .NET.NET Aspire-app-host uit.

  2. Open de Azure Opslagverkenner.

  3. Bekijk het deelvenster Explorer.

  4. Selecteer de link Vernieuw alles om de lijst met opslagaccounts te vernieuwen.

  5. Vouw het knooppunt Emulator & Attached uit.

  6. Vouw het Opslagaccounts knooppunt uit.

  7. U zou een opslagaccount met de naam van uw resource als voorvoegsel moeten zien.

    Azure Storage Explorer: Opslagresource van Azurite gedetecteerd.

U kunt het opslagaccount en de inhoud ervan verkennen met behulp van de Azure Storage Explorer. Zie Azurevoor meer informatie over het gebruik van de Storage Explorer.

De Azure Queue Storage-resource toevoegen

Registreer in uw app-hostproject de Azure Queue Storage-integratie door een aanroep te koppelen aan AddQueues op het IResourceBuilder<IAzureStorageResource> exemplaar dat door AddAzureStoragewordt geretourneerd. In het volgende voorbeeld ziet u hoe u een Azure Queue Storage-resource met de naam storage en een wachtrijresource met de naam queuestoevoegt:

var builder = DistributedApplication.CreateBuilder(args);

var queues = builder.AddAzureStorage("storage")
                    .AddQueues("queues");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(queues);

// After adding all resources, run the app...

De voorgaande code:

  • Hiermee wordt een Azure Storage-resource met de naam storagetoegevoegd.
  • Hiermee voegt u een wachtrij met de naam queues toe aan de opslagresource.
  • Voegt de storage resource toe aan de ExampleProject en wacht tot deze gereed is voordat het project wordt gestart.

Gezondheidscontroles voor hostingintegratie

De integratie van Azure Storage-hosting voegt automatisch een statuscontrole toe voor de opslagresource. Het wordt alleen toegevoegd bij uitvoering als emulator en controleert of de Azurite-container draait en of er een verbinding tot stand kan worden gebracht. De hostingintegratie is afhankelijk van de 📦 AspNetCore.HealthChecks.Azure. Storage.Blobs NuGet-pakket.

integratie van Client

Installeer het 📦Aspire.Azure.Storage.Queues NuGet-pakket in het project dat de Azure Queue Storage-client gebruikt, om aan de slag te gaan met de .NET AspireAzure Queue Storage-clientintegratie. De Azure Queue Storage-clientintegratie registreert een QueueServiceClient exemplaar dat u kunt gebruiken om te communiceren met Azure Queue Storage.

dotnet add package Aspire.Azure.Storage.Queues

Azure Queue Storage-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddAzureQueueClient-extensiemethode aan op een IHostApplicationBuilder om een QueueServiceClient te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddAzureQueueClient("queue");

Vervolgens kunt u het QueueServiceClient exemplaar ophalen met behulp van afhankelijkheidsinjectie. Bijvoorbeeld om de client op te halen uit een service:

public class ExampleService(QueueServiceClient client)
{
    // Use client...
}

Configuratie

De integratie van .NET AspireAzure Queue Storage biedt meerdere opties voor het configureren van de QueueServiceClient op basis van de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van AddAzureQueueClient:

builder.AddAzureQueueClient("queue");

Vervolgens wordt de verbindingsreeks opgehaald uit de ConnectionStrings configuratiesectie en worden twee verbindingsindelingen ondersteund:

Service-URI

De aanbevolen methode is om een ServiceUrite gebruiken, die werkt met de eigenschap AzureStorageQueuesSettings.Credential om een verbinding tot stand te brengen. Als er geen referentiegegevens zijn geconfigureerd, wordt de Azure.Identity.DefaultAzureCredential gebruikt.

{
  "ConnectionStrings": {
    "queue": "https://{account_name}.queue.core.windows.net/"
  }
}
Verbindingsreeks

U kunt ook een Azure Storage-verbindingsreeks gebruiken.

{
  "ConnectionStrings": {
    "queue": "AccountName=myaccount;AccountKey=myaccountkey"
  }
}

Zie Azure Storage-verbindingsreeksen configurerenvoor meer informatie.

Configuratieproviders gebruiken

De integratie van .NET AspireAzure Queue Storage ondersteunt Microsoft.Extensions.Configuration. Hiermee worden de AzureStorageQueuesSettings en QueueClientOptions vanuit de configuratie geladen met behulp van de Aspire:Azure:Storage:Queues-sleutel. Het volgende codefragment is een voorbeeld van een appsettings.json-bestand waarmee een aantal van de opties wordt geconfigureerd:

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Zie Aspirevoor het volledige Azure Storage Queues client-integratieschema JSON.Azure. Data.Queues/ConfigurationSchema.json.

Inline delegeringen gebruiken

U kunt de Action<AzureStorageQueuesSettings> configureSettings gedelegeerde ook doorgeven om bepaalde of alle opties inline in te stellen, bijvoorbeeld om statuscontroles te configureren:

builder.AddAzureQueueClient(
    "queue",
    settings => settings.DisableHealthChecks = true);

U kunt de QueueClientOptions ook instellen met behulp van Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder gedelegeerde, de tweede parameter van de AddAzureQueueClient methode. Als u bijvoorbeeld het eerste deel van de gebruikersagent-headers wilt instellen voor alle aanvragen van deze client:

builder.AddAzureQueueClient(
    "queue",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.Diagnostics.ApplicationId = "myapp"));

statuscontroles voor Client integratie

Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

De integratie van .NET AspireAzure Queue Storage:

  • Hiermee wordt de gezondheidscontrole toegevoegd wanneer AzureStorageQueuesSettings.DisableHealthChecksfalseis, waarmee geprobeerd wordt verbinding te maken met de Azure Queue Storage.
  • Kan worden geïntegreerd met het /health HTTP-eindpunt, waarmee is vastgesteld dat alle geregistreerde gezondheidscontroles moeten slagen voordat de app als gereed wordt beschouwd om verkeer te accepteren.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch configuraties in voor logboekregistratie, tracering en metrieken, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De integratie van .NET AspireAzure Queue Storage maakt gebruik van de volgende logboekcategorieën:

  • Azure.Core
  • Azure.Identity

Tracering

De integratie van .NET AspireAzure Queue Storage verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

  • Azure.Storage.Queues.QueueClient

Statistieken

De integratie van .NET AspireAzure Queue Storage biedt momenteel geen ondersteuning voor metriek door beperkingen van de Azure SDK.

Zie ook