.NET Aspire Azure Queue Storage-integrationen

Artikel
03/22/2025

omfattar: Hosting-integration och Client integrering

Azure Queue Storage är en tjänst för lagring av ett stort antal meddelanden som kan nås var som helst i världen via autentiserade anrop. Med integreringen .NET AspireAzure Queue Storage kan du ansluta till befintliga Azure Queue Storage-instanser eller skapa nya instanser från .NET program.

Värdintegrering

.NET .NET Aspire Azure Storage integrerar genom att modellera de olika lagringsresurserna som följande typer:

AzureStorageResource: Representerar en Azure lagringsresurs.
AzureStorageEmulatorResource: Representerar en Azure-lagringsemmulatorresurs (Azurite).
AzureBlobStorageResource: Representerar en Azure Blob-lagringsresurs.
AzureQueueStorageResource: Representerar en Azure lagringsresurs för kö.
AzureTableStorageResource: Representerar en Azure tabelldatalagringsresurs.

Om du vill komma åt dessa typer och API:er för att uttrycka dem, lägger du till 📦Aspire.Hosting.Azure.Lagring NuGet-paketet i appvärdprojekt.

.NET CLI
PaketReferens

dotnet add package Aspire.Hosting.Azure.Storage

<PackageReference Include="Aspire.Hosting.Azure.Storage"
                  Version="*" />

För mer information, se dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägg till Azure lagringsresurs

I ditt appvärdprojekt, anropa AddAzureStorage för att lägga till och returnera en Azure Storage-resursbyggare.

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...

När du lägger till en AzureStorageResource i appvärden exponeras andra användbara API:er för att lägga till Azure blob-, kö- och tabelllagringsresurser. Med andra ord måste du lägga till en AzureStorageResource innan du lägger till någon av de andra lagringsresurserna.

Viktig

När du anropar AddAzureStorageanropas implicit AddAzureProvisioning– vilket ger stöd för att generera Azure resurser dynamiskt under appstarten. Appen måste konfigurera lämplig prenumeration och plats. För mer information, se Lokal etablering: Konfiguration.

Genererad Bicep-konfiguration

Om du är ny på Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med .NET.NET Aspirebehöver du inte skriva Bicep för hand, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app genereras den skapade Bicep-filen tillsammans med manifestfilen. När du lägger till en Azure Storage-resurs genereras följande Bicep:

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

param principalType string

param principalId 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

Föregående Bicep är en modul som etablerar ett Azure Storage-konto med följande standardvärden:

kind: Typen av lagringskonto. Standardvärdet är StorageV2.
sku: SKU:n för lagringskontot. Standardvärdet är Standard_GRS.
properties: Egenskaperna för lagringskontot:
- accessTier: Åtkomstnivån för lagringskontot. Standardvärdet är Hot.
- allowSharedKeyAccess: Ett booleskt värde som anger om lagringskontot tillåter att begäranden auktoriseras med kontoåtkomstnyckeln. Standardvärdet är false.
- minimumTlsVersion: Den lägsta TLS-version som stöds för lagringskontot. Standardvärdet är TLS1_2.
- networkAcls: Nätverks-ACL:er för lagringskontot. Standardvärdet är { defaultAction: 'Allow' }.

Förutom lagringskontot skapar det även en blobcontainer.

Följande rolltilldelningar läggs till i lagringskontot för att ge ditt program åtkomst. Mer information finns i inbyggda roller för Azure rollbaserad åtkomstkontroll (Azure RBAC):

Roll/ID	Beskrivning
Storage Blob Data-deltagare `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Läsa, skriva och ta bort Azure Lagringscontainrar och blobar.
Bidragsgivare för lagringstabellens data `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Läsa, skriva och ta bort Azure Lagringstabeller och entiteter.
Lagringsködatadeltagare `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Läsa, skriva och ta bort Azure Lagringsköer och kömeddelanden.

Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa tillhandahållandeinfrastruktur

Alla .NET AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör anpassning av den genererade Bicep genom att tillhandahålla en flytande API för att konfigurera Azure-resurser med hjälp av ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API:et. Du kan till exempel konfigurera kind, sku, propertiesoch mycket mer. I följande exempel visas hur du anpassar Azure Storage-resursen:

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");
    });

Föregående kod:

Kedjar ett anrop till ConfigureInfrastructure-API:et:
- Parametern infra är en instans av den AzureResourceInfrastructure typen.
- De tillgängliga resurserna hämtas genom att anropa metoden GetProvisionableResources().
- Den enda StorageAccount hämtas.
- StorageAccount.AccessTier tilldelas till StorageAccountAccessTier.Cool.
- StorageAccount.Sku tilldelas till en ny StorageSku med en Name av PremiumZrs.
- En tagg läggs till i lagringskontot med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa Azure Storage-resursen. Mer information finns i Azure.Provisioning.Storage.

Ansluta till ett befintligt Azure Storage-konto

Du kan ha ett befintligt Azure Lagringskonto som du vill ansluta till. I stället för att du representerar en ny Azure Storage-resurs kan du lägga till en anslutningssträng till appens värd. Om du vill lägga till en anslutning till ett befintligt Azure Storage-konto anropar du metoden AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Obs

Anslutningssträngar används för att representera ett brett spektrum av anslutningsinformation, inklusive databasanslutningar, meddelandeköer, slutpunkts-URI:er och andra tjänster. I .NET.NET Aspire nomenklatur används termen "anslutningssträng" för att representera alla typer av anslutningsinformation.

Anslutningssträngen konfigureras i appvärdens konfiguration, vanligtvis under Användarhemligheter, under avsnittet ConnectionStrings. Appen injicerar den här anslutningssträngen som en miljövariabel i alla beroende resurser, till exempel:

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

Den beroende resursen kan komma åt den inmatade anslutningssträngen genom att anropa metoden GetConnectionString och skicka anslutningsnamnet som parameter, i det här fallet "blobs". API:et GetConnectionString är en förkortning för IConfiguration.GetSection("ConnectionStrings")[name].

Lägg till Azure Storage-emulator-resurs

Om du vill lägga till en Azure Storage-emulatorresurs kopplar du ett anrop på en IResourceBuilder<AzureStorageResource> till RunAsEmulator API:t.

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du anropar RunAsEmulatorkonfigureras dina lagringsresurser att köras lokalt med hjälp av en emulator. Emulatorn i det här fallet är Azurite. Azurite-emulatorn med öppen källkod ger en kostnadsfri lokal miljö för att testa dina Azure Blob-, Queue Storage- och Table Storage-appar och det är en perfekt följeslagare till .NET AspireAzure värdintegrering. Azurite är inte installerat, i stället är det tillgängligt för .NET.NET Aspire som en container. När du lägger till en container i appvärden, som du ser i föregående exempel med mcr.microsoft.com/azure-storage/azurite avbildningen, skapas och startas containern när appvärden startar. Mer information finns i Livscykel för containerresurser.

Konfigurera Azurite-container

Det finns olika konfigurationer tillgängliga för containerresurser, till exempel kan du konfigurera containerns portar, miljövariabler, det är livslängdmed mera.

Konfigurera Azurite-containerportar

Som standard exponerar Azurite-containern när den konfigureras av .NET.NET Aspireföljande slutpunkter:

Slutpunkt	Containerhamn	Värdport
`blob`	10 000	dynamisk
`queue`	10001	dynamisk
`table`	10002	dynamisk

Porten som de lyssnar på är dynamisk som standard. När containern startar mappas portarna till en slumpmässig port på värddatorn. För att konfigurera slutpunktsportarna kedjar du anrop på containerresursverktyget som tillhandahålls av metoden RunAsEmulator enligt följande exempel:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Föregående kod konfigurerar Azurite-containerns befintliga blob, queueoch table slutpunkter för att lyssna på portar 27000, 27001respektive 27002. Azurite-containerns portar mappas till värdportarna enligt följande tabell:

Slutpunktsnamn	Portmappning (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

Konfigurera Azurite-container med beständig livslängd

Om du vill konfigurera Azurite-containern med en beständig livslängd anropar du metoden WithLifetime på Azurite-containerresursen och skickar ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Mer information finns i Containerresursens livslängd.

Konfigurera Azurite-container med datavolym

Om du vill lägga till en datavolym i Azure Storage-emulatorresursen anropar du metoden WithDataVolume på Azure Storage-emulatorresursen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Datavolymen används för att bevara Azurite-data utanför containerns livscykel. Datavolymen monteras på sökvägen /data i containern Azurite, och när parameter name inte tillhandahålls formateras namnet som .azurite/{resource name}. Mer om datavolymer och varför de föredras framför bind mountsfinns i Docker dokument: Volymer.

Konfigurera Azurite-container med databindningsmontering

Om du vill lägga till en databindningsmontering till Azure Storage-emulatorresursen anropar du metoden WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Viktig

Data bind mounts har begränsade funktioner jämfört med volumes som erbjuder bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

Databindningar förlitar sig på värdmaskinens filsystem för att bevara Azurite-data mellan omstarter av containrar. Databindningen monteras på sökvägen ../Azurite/Data på värdmaskinen relativt till appvärdkatalogen (IDistributedApplicationBuilder.AppHostDirectory) i Azurite-containern. Mer information om bindningsmonteringar finns i Docker dokumentationen: Bindningsmonteringar.

Ansluta till lagringsresurser

När .NET.NET Aspire applikationsvärd körs kan externa verktyg, såsom Azure Storage Explorer, komma åt lagringsresurserna. Om lagringsresursen körs lokalt med Azurite hämtas den automatiskt av Azure Storage Explorer.

Obs

Azure Storage Explorer identifierar Azurite-lagringsresurser förutsatt att standardportarna används. Om du har konfigurerat Azurite-containern för att använda olika portarmåste du konfigurera Azure Storage Explorer för att ansluta till rätt portar.

Följ dessa steg för att ansluta till lagringsresursen från Azure Storage Explorer:

Kör .NET.NET Aspire applikationsvärd.
Öppna Azure Storage Explorer.
Visa fönstret Explorer.
Klicka på länken Uppdatera alla för att uppdatera lagringskontolistan.
Expandera noden Emulator & Ansluten.
Expandera noden Lagringskonton.
Du bör se ett lagringskonto med resursens namn som prefix:

Du kan utforska lagringskontot och dess innehåll med hjälp av Azure Storage Explorer. Mer information om hur du använder Azure Storage Explorer finns i Komma igång med Storage Explorer.

Lägg till Azure Queue Storage-resurs

I ditt appvärdprojekt registrerar du integreringen Azure Queue Storage genom att kedja ett anrop till AddQueues på den IResourceBuilder<IAzureStorageResource>-instans som returneras av AddAzureStorage. I följande exempel visas hur du lägger till en Azure Queue Storage-resurs med namnet storage och en köresurs med namnet queues:

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...

Föregående kod:

Lägger till en Azure Storage-resurs med namnet storage.
Lägger till en kö med namnet queues till lagringsresursen.
Lägger till den storage resursen i ExampleProject och väntar på att den ska vara klar innan projektet startas.

Värdskap av hälsokontroller för integration

Azure-lagringsvärdintegration skapar automatiskt en hälsokontroll för lagringsresursen. Den läggs bara till när den körs som en emulator och verifierar att Azurite-containern körs och att en anslutning kan upprättas till den. Integrationen av hosting förlitar sig på 📦 AspNetCore.HealthChecks.Azure.Storage.Blobs NuGet-paketet.

Client integrering

Kom igång med klientintegrering av .NET AspireAzure Queue Storage genom att installera 📦Aspire.Azure. Storage.Queues NuGet-paket i det klientkrävande projektet, dvs. projektet för det program som använder Azure Queue Storage-klienten. Klientintegrering Azure Queue Storage registrerar en QueueServiceClient instans som du kan använda för att interagera med Azure Queue Storage.

.NET CLI
PaketReferens

dotnet add package Aspire.Azure.Storage.Queues

<PackageReference Include="Aspire.Azure.Storage.Queues"
                  Version="*" />

Lägg till Azure Queue Storage-klient

I Program.cs-filen för ditt klientförbrukande projekt, anropar du AddAzureQueueClient-tilläggsmetoden på valfri IHostApplicationBuilder för att registrera en QueueServiceClient för användning via beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddAzureQueueClient("queue");

Du kan sedan hämta QueueServiceClient-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta klienten från en tjänst:

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

Konfiguration

Integreringen .NET AspireAzure Queue Storage innehåller flera alternativ för att konfigurera QueueServiceClient baserat på kraven och konventionerna i projektet.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar AddAzureQueueClient:

builder.AddAzureQueueClient("queue");

Sedan hämtas anslutningssträngen från avsnittet ConnectionStrings konfiguration och två anslutningsformat stöds:

Tjänst-URI

Den rekommenderade metoden är att använda en ServiceUri, som fungerar med egenskapen AzureStorageQueuesSettings.Credential för att upprätta en anslutning. Om inga autentiseringsuppgifter har konfigurerats används Azure.Identity.DefaultAzureCredential.

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

Anslutningssträng

Du kan också använda en Azure Storage-anslutningssträng.

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

För mer information, se Konfigurera lagringsanslutningssträngar Azure.

Använda konfigurationsprovidrar

Integreringen .NET AspireAzure Queue Storage stöder Microsoft.Extensions.Configuration. Den läser in AzureStorageQueuesSettings och QueueClientOptions från konfigurationen med hjälp av Aspire:Azure:Storage:Queues-nyckeln. Följande kodfragment är ett exempel på en appsettings.json fil som konfigurerar några av alternativen:

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

Det fullständiga Azure Storage Queues klientintegreringsschemat JSON finns i Aspire.Azure. Data.Queues/ConfigurationSchema.json.

Använd inline-delegater

Du kan också överföra delegering Action<AzureStorageQueuesSettings> configureSettings för att sätta upp vissa eller alla alternativ direkt, till exempel för att konfigurera hälsokontroller.

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

Du kan också konfigurera QueueClientOptions med hjälp av Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder delegat, den andra parametern i metoden AddAzureQueueClient. Om du till exempel vill ställa in den första delen av användaragenthuvudena för alla begäranden som görs av den här klienten:

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

Client hälsokontroller för integrering

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Integrering av .NET AspireAzure Queue Storage:

Lägger till hälsokontrollen när AzureStorageQueuesSettings.DisableHealthChecks är false, som försöker ansluta till Azure Queue Storage.
Integrerar med /health HTTP-slutpunkt, som specificerar att alla registrerade hälsokontroller måste passera för att appen ska anses vara redo att ta emot trafik.

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

Integreringen .NET AspireAzure Queue Storage använder följande loggkategorier:

Azure.Core
Azure.Identity

Spårning

Integreringen .NET AspireAzure Queue Storage genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

Azure.Storage.Queues.QueueClient

Mått

Integreringen av .NET AspireAzure Queue Storage stöder för närvarande inte mått som standard på grund av begränsningar med Azure SDK.

Dela via