.NET Aspire Azure Blob Storage integráció

Tartalmazza: Üzemeltetési integráció és Client integráció

Azure Blob Storage szolgáltatás nagy mennyiségű strukturálatlan adat tárolására szolgál. A .NET AspireAzure Blob Storage integráció lehetővé teszi, hogy meglévő Azure Blob Storage-példányokhoz csatlakozzon, vagy új példányokat hozzon létre .NET alkalmazásokból.

Üzemeltetési integráció

A .NET.NET AspireAzure Storage a különböző tárolási erőforrásokat az alábbi típusok szerint modelleli:

• AzureStorageResource: Egy Azure Storage-erőforrást jelöl.
• AzureStorageEmulatorResource: Egy Azure Storage emulátorerőforrást (Azurite) jelöl.
• AzureBlobStorageResource: Egy Azure Blob Storage-erőforrást jelöl.
• AzureQueueStorageResource: Egy Azure Queue Storage-erőforrást jelöl.
• AzureTableStorageResource: Egy Azure Table Storage-erőforrást jelöl.

Az ilyen típusokhoz és API-khoz való hozzáféréshez adja hozzá a 📦Aspire.Hosting.Azure.Storage NuGet-csomagot az alkalmazáshost projekt részéhez.

dotnet add package Aspire.Hosting.Azure.Storage

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

További információért lásd: dotnet add package vagy Csomagfüggőségek kezelése a .NET alkalmazásokban.

Azure Storage-erőforrás hozzáadása

Az alkalmazásgazda projektben hívja meg a AddAzureStorage-t, hogy hozzáadjon és visszaadjon egy Azure tároló erőforrás építőt.

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

Amikor hozzáadsz egy AzureStorageResource az alkalmazásgazdához, ezzel egyéb hasznos API-kat teszel elérhetővé a Azure Blob-, Queue- és Table-storage erőforrások hozzáadásához. Más szóval a többi tárolási erőforrás hozzáadása előtt hozzá kell adnia egy AzureStorageResource.

Generált Bicep előállítás

Ha új a Bicep-hoz, ez egy domain-specifikus nyelv erőforrások definiálására. Önnek .NET.NET Aspiresegítségével nem kell kézzel írnia a Bicepet, mivel a kiépítési API-k generálják azt Ön helyett. Az alkalmazás közzétételekor a létrehozott Bicep a jegyzékfájl mellett kerül kimenetként megjelenítésre. Azure Storage-erőforrás hozzáadásakor a következő Bicep jön létre:

@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

Az előző Bicep egy modul, amely egy Azure Storage-fiókot helyez üzembe az alábbi alapértelmezett értékekkel:

• kind: A tárfiók típusa. Az alapértelmezett érték a StorageV2.
• sku: A tárolási fiók SKU-ja. Az alapértelmezett érték a Standard_GRS.
• properties: A tárfiók tulajdonságai:
  • accessTier: A tárfiók hozzáférési szintje. Az alapértelmezett érték a Hot.
  • allowSharedKeyAccess: Logikai érték, amely jelzi, hogy a tárfiók engedélyezi-e a fiók hozzáférési kulcsával való engedélyezést. Az alapértelmezett érték a false.
  • minimumTlsVersion: A tárfiók minimálisan támogatott TLS-verziója. Az alapértelmezett érték a TLS1_2.
  • networkAcls: A tárfiók hálózati ACL-jeit. Az alapértelmezett érték a { defaultAction: 'Allow' }.

A tárfiókra kívül egy blobtárolót is létrehoz.

A következő szerepkör-hozzárendelések lesznek hozzáadva a tárfiókhoz az alkalmazás hozzáférésének biztosításához. További információért tekintse meg a beépített Azure szerepköralapú hozzáférés-vezérlési (Azure RBAC) szerepköröket:.

A létrehozott Bicep kiindulási pont, és testre szabható az adott követelményeknek megfelelően.

Ellátási infrastruktúra testreszabása

Minden .NET AspireAzure erőforrás a AzureProvisioningResource típusú alosztály. Ez a típus lehetővé teszi a létrehozott Bicep testreszabását azáltal, hogy egy folyékony API-t biztosít a Azure erőforrások konfigurálásához – a ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API használatával. Konfigurálhatja például a kind, sku, propertiesstb. Az alábbi példa bemutatja, hogyan szabhatja testre a Azure Storage-erőforrást:

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

Az előző kód:

• Egy hívást láncol az ConfigureInfrastructure API-hoz:
  • A infra paraméter a AzureResourceInfrastructure típusú példány.
  • A kiosztható erőforrások a GetProvisionableResources() metódus meghívásával kérhetők le.
  • Az egyetlen StorageAccount lekérve.
  • A StorageAccount.AccessTier hozzá van rendelve StorageAccountAccessTier.Cool.
  • Az StorageAccount.Sku egy új StorageSku-hez van rendelve, amelynek Name-je PremiumZrs.
  • A rendszer hozzáad egy címkét a tárfiókhoz egy ExampleKey kulccsal és egy Example valueértékkel.

A Azure Storage-erőforrás testreszabásához számos további konfigurációs lehetőség áll rendelkezésre. További információ: Azure.Provisioning.Storage.

Csatlakozás meglévő Azure Storage-fiókhoz

Lehet, hogy rendelkezik egy meglévő Azure Storage-fiókkal, amelyhez csatlakozni szeretne. Ahelyett, hogy új Azure Storage-erőforrást hozna létre, hozzáadhat egy kapcsolati karakterláncot az alkalmazásházigazdához. Ha meglévő Azure Storage-fiókhoz szeretne kapcsolatot létesíteni, hívja meg a AddConnectionString metódust:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

A csatlakozási karakterlánc az alkalmazásházigazda beállításaiban van beállítva, általában a Felhasználói titkos kódokalatt, a ConnectionStrings szakaszban. Az alkalmazásgazda környezeti változóként injektálja ezt a kapcsolati sztringet az összes függő erőforrásba, például:

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

A függő erőforrás a GetConnectionString metódus meghívásával és a kapcsolatnév paraméterként való átadásával érheti el az injektált kapcsolati sztringet, ebben az esetben "blobs". A GetConnectionString API a IConfiguration.GetSection("ConnectionStrings")[name]rövidített kifejezése.

Azure Storage Emulator-erőforrás hozzáadása

Ha egy Azure hívást szeretne láncolni a IResourceBuilder<AzureStorageResource> API-hoz, hogy hozzáadjon egy RunAsEmulator Storage emulátor-erőforrást:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Amikor meghívja RunAsEmulator, a tárolóerőforrásokat úgy konfigurálja, hogy helyileg fussanak egy emulátor használatával. Az emulátor ebben az esetben Azurite. Az Azurite nyílt forráskódú emulátor ingyenes helyi környezetet biztosít a Azure Blob-, Queue Storage- és Table Storage-alkalmazások teszteléséhez, és tökéletes társ a .NET AspireAzure üzemeltetési integrációjához. Az Azurite nincs telepítve, hanem .NETés.NET Aspire számára tárolóként érhető el. Amikor hozzáad egy tárolót az alkalmazás gazdagépéhez, az előző példában bemutatott módon a mcr.microsoft.com/azure-storage/azurite képen, az létrehozza és elindítja a tárolót az alkalmazásgazda indításával. További információért lásd Tárolóerőforrás-életciklus.

Azurite-tároló konfigurálása

A tárolóerőforrások különböző konfigurációkkal érhetők el, például konfigurálhatja a tároló portjait, környezeti változóit, élettartamátstb.

Azurite-tárolóportok konfigurálása

Alapértelmezés szerint az Azurite-tároló .NET.NET Aspirekonfigurálásakor a következő végpontokat teszi elérhetővé:

Az a port, amelyen figyelnek, alapértelmezés szerint dinamikus. A tároló indításakor a portok egy véletlenszerű porthoz vannak hozzárendelve a gazdagépen. A végpontportok konfigurálásához lánchívásokat kell futtatnia a RunAsEmulator metódus által biztosított tárolóerőforrás-szerkesztőn az alábbi példában látható módon:

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

Az előző kód konfigurálja az Azurite-tároló meglévő blob, queueés table végpontjait a portok 27000, 27001és 27002figyelésére. Az Azurite-tároló portja a gazdagépportok szerint van leképezve az alábbi táblázatban látható módon:

Az azurite-tároló konfigurálása állandó élettartammal

Ha az Azurite-tárolót állandó élettartammal szeretné konfigurálni, hívja meg az WithLifetime metódust az Azurite-tároló erőforrásán, és adja át a 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...

További információ: tárolóerőforrás élettartama.

Azurite-tároló konfigurálása adattérfogattal

Ha adatkötetet szeretne hozzáadni a Azure Storage emulátor erőforráshoz, hívja meg a WithDataVolume metódust a Azure Storage emulátor erőforráson:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Az adatkötet az Azurite-adatok tárolójának életciklusán kívüli megőrzésére szolgál. Az adatkötet az Azurite-tároló /data elérési útján van csatlakoztatva, és ha nincs megadva name paraméter, a név .azurite/{resource name}szerint van formázva. További információért az adatkötetekről és arról, hogy miért részesítik őket előnyben a hozzárendelt csatolásokkal szemben, tekintse meg a Docker dokumentumokat: Adatkötetek.

Az Azurite-tároló konfigurálása adat-kötéses csatolmány használatával

Ha adatkötési csatlakoztatást szeretne hozzáadni a Azure Storage Emulator erőforráshoz, hívja meg a WithDataBindMount metódust:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Az adatkötési csatlakoztatások a gazdagép fájlrendszerére támaszkodnak az Azurite-adatok tároló-újraindítások közötti megőrzéséhez. Az adatkötés csatolása a gazdagépen lévő ../Azurite/Data elérési útvonalra van csatolva az Azurite tárolóban lévő alkalmazásgazda könyvtárhoz (IDistributedApplicationBuilder.AppHostDirectory) képest. Az adatkötési csatlakoztatásokkal kapcsolatos további információkért lásd Docker dokumentumokat: Kötési csatlakoztatások.

Csatlakozás tárolási erőforrásokhoz

A .NET.NET Aspire alkalmazáskiszolgáló futtatásakor a tárolási erőforrások külső eszközökkel, például a Azure Storage Explorer érhetők el. Ha a tárolási erőforrás helyileg fut az Azurite használatával, a Azure Storage Explorer automatikusan felveszi.

Ha Azure Storage Explorerből szeretne csatlakozni a tárolóerőforráshoz, kövesse az alábbi lépéseket:

1. Futtassa a .NET.NET Aspire alkalmazás hosztját.

2. Nyissa meg a Azure Storage Explorert.

3. Tekintse meg a Explorer panelt.

4. Válassza az Az összes frissítése hivatkozásra kattintva frissítse a tárfiókok listáját.

5. Bontsa ki a Emulator & Csatolt csomópontot.

6. Nyissa meg a Tárolófiókok csomópontot.

7. Látnia kell egy tárolási fiókot, amelynek neve előtagként az erőforrás nevével kezdődik.

   

A tárfiókot és annak tartalmát a Azure Storage Explorer használatával tekintheti meg. További információ a Azure Storage Explorer használatáról: A Storage Explorer használatának első lépései.

Azure Blob Storage erőforrás hozzáadása

A(z) alkalmazásgazda projektjében regisztrálja a Azure Blob Storage integrációt úgy, hogy láncol egy AddBlobs hívást a AddAzureStorage által visszaadott IResourceBuilder<IAzureStorageResource> példányra. Az alábbi példa bemutatja, hogyan vehet fel Azure Blob Storagestorage nevű erőforrást és egy blobsnevű blobtárolót:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(blobs)
       .WaitFor(blobs);

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

Az előző kód:

• Hozzáad egy Azurenevű storage Storage-erőforrást.
• Láncol egy hívást a RunAsEmulator-hoz, hogy konfigurálja a tároló erőforrást úgy, hogy helyben fusson egy emulátor segítségével. Az emulátor ebben az esetben Azurite.
• Hozzáad egy blobs nevű blobtárolót a tárolási erőforráshoz.
• Hozzáadja a blobs erőforrást a ExampleProject-hez, és megvárja, amíg az készen nem áll a projekt megkezdése előtt.

Integrációs állapotellenőrzések üzemeltetése

A Azure Storage-üzemeltetés integrációja automatikusan hozzáadja a tárolási erőforrás állapot-ellenőrzését. Csak emulátorként való futtatáskor lesz hozzáadva, és ellenőrzi, hogy az Azurite-tároló fut-e, és hogy létre lehet-e hozni vele kapcsolatot. A tárhelyintegráció az 📦 AspNetCore.HealthChecks.AzureStorage.Blobs NuGet csomagra támaszkodik.

Client integráció

Az .NET AspireAzure Blob Storage ügyfélintegráció megkezdéséhez telepítse a 📦Aspire.Azure.Storage.Blobs NuGet-csomagot abba a projektbe, amely az alkalmazást tartalmazza, ami a Azure Blob Storage ügyfelet használja. A Azure Blob Storage ügyfélintegráció regisztrál egy BlobServiceClient példányt, amelyet felhasználhat a Azure Blob Storage-val való interakcióra.

dotnet add package Aspire.Azure.Storage.Blobs

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

Azure Blob Storage-ügyfél hozzáadása

Az ügyfél által használt projekt Program.cs fájljában hívja meg a AddAzureBlobClient bővítménymetódusát bármelyik IHostApplicationBuilder esetében, hogy regisztráljon egy BlobServiceClient-at a függőség-injektáló tárolón keresztül való használatra. A metódus egy kapcsolatnévparamétert használ.

builder.AddAzureBlobClient("blobs");

Ezután függőséginjektálással lekérheti a BlobServiceClient-példányt. Például az ügyfél adatainak lekérése egy szolgáltatásból:

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

Konfiguráció

A .NET AspireAzure Blob Storage integráció több lehetőséget is kínál a BlobServiceClient konfigurálásához a projekt követelményei és konvenciói alapján.

Kapcsolati karakterlánc használata

Ha kapcsolati sztringet használ a ConnectionStrings konfigurációs szakaszból, megadhatja a kapcsolati sztring nevét AddAzureBlobClienthívásakor:

builder.AddAzureBlobClient("blobs");

Ezután a kapcsolati karakterláncot lekérjük a ConnectionStrings konfigurációs szakaszból, és két kapcsolatformátumot támogatunk.

Szolgáltatás URI-ja

Az ajánlott módszer egy ServiceUrihasználata, amely a AzureStorageBlobsSettings.Credential tulajdonsággal együttműködve hoz létre kapcsolatot. Ha nincs hitelesítő adat konfigurálva, a rendszer a Azure.Identity.DefaultAzureCredential használja.

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

Kapcsolati karakterlánc

Másik lehetőségként egy Azure tárolási kapcsolati karakterlánc is használható.

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

További információkért lásd: Tárolási kapcsolati sztringek konfigurálásaAzure.

Konfigurációs szolgáltatók használata

A .NET AspireAzure Blob Storage integráció támogatja a Microsoft.Extensions.Configuration. A AzureStorageBlobsSettings és BlobClientOptions elemeket a konfigurációból tölti be a Aspire:Azure:Storage:Blobs kulcs segítségével. Az alábbi kódrészlet egy példa egy appsettings.json fájlra, amely konfigurál néhány beállítást:

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

A teljes Azure Blob Storage ügyfél-integrációs JSON sémát lásd: Aspire.Azure. Storage.Blobs/ConfigurationSchema.json.

Beágyazott delegálók használata

A Action<AzureStorageBlobsSettings> configureSettings delegáltat is átadhatja az opciók egy részének vagy összesének beágyazott beállításához, például az állapot-ellenőrzések konfigurálásához.

builder.AddAzureBlobClient(
    "blobs",
    settings => settings.DisableHealthChecks = true);

A AddAzureBlobClient delegálttal is beállíthatja a BlobClientOptions-t, ami a Action<IAzureClientBuilder<BlobServiceClient, BlobClientOptions>> configureClientBuilder metódus második paramétere. Például, ha be szeretné állítani a felhasználói ügynök fejléceinek első részét az ügyfél által küldött összes kéréshez:

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

Client integrációs egészségügyi ellenőrzések

Alapértelmezés szerint az .NET.NET Aspire integrációk lehetővé teszik állapotellenőrzéseket az összes szolgáltatás esetében. További információ: .NET.NET Aspire integrációk áttekintése.

A .NET AspireAzure Blob Storage integrációja:

• Hozzáadja az állapot-ellenőrzést, amikor a AzureStorageBlobsSettings.DisableHealthChecksfalse, és megpróbál csatlakozni a Azure Blob Storage-höz.
• Integrálható a /health HTTP-végponttal, amely meghatározza, hogy az összes regisztrált állapot-ellenőrzésnek át kell mennie ahhoz, hogy az alkalmazás készen álljon a forgalom elfogadására.

Megfigyelhetőség és telemetria

.NET .NET Aspire integrációk automatikusan beállítják a naplózási, nyomkövetési és metrikák konfigurációit, amelyeket más néven a megfigyelhetőség alappillérei. Az integráció megfigyelhetőségéről és telemetriáról további információt .NET.NET Aspire integrációk áttekintésében. A háttérszolgáltatástól függően egyes integrációk csak bizonyos funkciókat támogatnak. Egyes integrációk például támogatják a naplózást és a nyomkövetést, a metrikákat azonban nem. A telemetriai funkciók a Konfiguráció szakaszban ismertetett technikákkal is letilthatók.

Fakitermelés

Az .NET AspireAzure Blob Storage integráció a következő naplókategóriákat használja:

• Azure.Core
• Azure.Identity

Nyomkövetés

A .NET AspireAzure Blob Storage integráció a következő nyomkövetési tevékenységeket bocsátja ki a OpenTelemetryhasználatával:

• Azure.Storage.Blobs.BlobContainerClient

Metrikák

A .NET AspireAzure Blob Storage integráció jelenleg nem támogatja alapértelmezés szerint a metrikákat a Azure SDK korlátozásai miatt.

Lásd még:

• Azure Blob Storage dokumentumok
• .NET .NET Aspire integrációk
• .NET Aspire GitHub repo