integrace .NET AspireAzure Blob Storage

Článek
12/16/2024

zahrnuje:integrace hostování a Client integrace

Azure Blob Storage je služba pro ukládání velkých objemů nestrukturovaných dat. Integrace .NET AspireAzure Blob Storage umožňuje připojit se k existujícím instancím Azure Blob Storage nebo vytvářet nové instance z aplikací .NET.

Integrace hostování

.NET .NET Aspire Azure Storage modely pro integraci hostování modelují různé prostředky úložiště jako následující typy:

AzureStorageResource: Představuje úložný prostředek Azure.
AzureStorageEmulatorResource: Představuje prostředek emulátoru úložiště Azure (Azurite).
AzureBlobStorageResource: Reprezentuje prostředek pro úložiště objektů blob Azure.
AzureQueueStorageResource: Představuje prostředek Azure Queue Storage.
AzureTableStorageResource: Představuje prostředek úložiště tabulek Azure.

Pokud chcete získat přístup k těmto typům a rozhraním API pro jejich vyjádření, přidejte 📦Aspire.Hosting.Azure. balíček NuGet úložiště v projektu hostitele app.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidejte prostředek úložiště Azure

V projektu hostitele aplikace zavolejte AddAzureStorage, abyste přidali a vrátili tvůrce prostředků Azure Storage.

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

Když do hostitele aplikace přidáte AzureStorageResource, zpřístupní další užitečná rozhraní API pro přidání prostředků Azure Blob, Queue a Table storage. Jinými slovy, před přidáním jakéhokoli jiného prostředku úložiště musíte přidat AzureStorageResource.

Důležitý

Když voláte AddAzureStorage, automaticky se volá AddAzureProvisioning, což přidává podporu pro dynamické generování prostředků Azure během spouštění aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Další informace naleznete v části Místní zřizování: Konfigurace.

Vygenerované zajišťování Bicep

Pokud začínáte s Bicep, jedná se o doménově specifický jazyk pro definování Azure prostředků. Díky .NET.NET Aspirenemusíte psát Bicep ručně, namísto toho, aby rozhraní API pro zřizování generovala Bicep za vás. Když publikujete aplikaci, vygenerovaný Bicep je uložen společně se souborem manifestu. Když přidáte prostředek Azure Storage, vygeneruje se následující Bicep:

přepnout Azure Bicep úložiště.

@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

Předchozí modul Bicep zřídí úložiště účtu Azure s následujícími výchozími nastaveními:

kind: Druh účtu úložiště. Výchozí hodnota je StorageV2.
sku: SKU účtu úložiště. Výchozí hodnota je Standard_GRS.
properties: Vlastnosti účtu úložiště:
- accessTier: Úroveň přístupu účtu úložiště. Výchozí hodnota je Hot.
- allowSharedKeyAccess: Logická hodnota, která označuje, jestli účet úložiště povoluje autorizaci požadavků s přístupovým klíčem účtu. Výchozí hodnota je false.
- minimumTlsVersion: Minimální podporovaná verze protokolu TLS pro účet úložiště. Výchozí hodnota je TLS1_2.
- networkAcls: Síťové ACL pro účet úložiště. Výchozí hodnota je { defaultAction: 'Allow' }.

Kromě účtu úložiště také vytváří kontejner objektů blob.

Následující přiřazení rolí jsou přidána do účtu úložiště, aby vaše aplikace získala přístup. Další informace najdete v integrovaných rolích Azure řízení přístupu na základě rolí (Azure RBAC).

Role / Identifikátor	Popis
Přispěvatel dat objektů blob služby Storage `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Čtení, zápis a odstranění kontejnerů a blobových objektů služby Azure Storage.
Přispěvatel dat do tabulek úložiště `0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Čtení, zápis a odstranění Azure tabulek a entit služby Storage
Přispěvatel dat fronty služby Storage `974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Čtení, zápis a odstraňování zpráv Azure frontách a frontách služby Storage.

Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení infrastruktury zřizování

Všechny zdroje .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicep tím, že poskytuje plynulé rozhraní API pro konfiguraci Azure prostředků pomocí ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API. Můžete například nakonfigurovat kind, sku, propertiesatd. Následující příklad ukazuje, jak přizpůsobit prostředek Azure Storage:

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

Předchozí kód:

Zřetězí volání rozhraní API ConfigureInfrastructure:
- Parametr infra je instance typu AzureResourceInfrastructure.
- Poskytovatelné prostředky se načtou voláním metody GetProvisionableResources().
- Načte se jeden StorageAccount.
- StorageAccount.AccessTier je přiřazen k StorageAccountAccessTier.Cool.
- StorageAccount.Sku je přiřazeno novému StorageSku s Name o hodnotě PremiumZrs.
- Do účtu úložiště se přidá značka s klíčem ExampleKey a hodnotou Example value.

K dispozici je mnoho dalších možností konfigurace pro přizpůsobení prostředku Azure Storage. Další informace najdete v tématu Azure.Provisioning.Storage.

Připojení k existujícímu účtu Azure Storage

Možná máte existující účet Azure Storage, ke kterému se chcete připojit. Místo toho, abyste vytvářeli nový prostředek Azure Storage, můžete do hostitele aplikace přidat připojovací řetězec. Pokud chcete přidat připojení k existujícímu účtu Azure Storage, zavolejte metodu 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...

Poznámka

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelův části ConnectionStrings. Hostitel aplikace vloží tento připojovací řetězec jako proměnnou prostředí do všech závislých prostředků, například:

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

Závislý prostředek se může dostat k vloženému připojovacímu řetězci voláním metody GetConnectionString a předáním názvu připojení jako parametru, v tomto případě "blobs". Rozhraní API GetConnectionString je zkratka pro IConfiguration.GetSection("ConnectionStrings")[name].

Přidání prostředku emulátoru úložiště Azure

Pokud chcete přidat prostředek emulátoru úložiště Azure, zřetězte volání IResourceBuilder<AzureStorageResource> do rozhraní RunAsEmulator API:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Při volání RunAsEmulatornakonfiguruje prostředky úložiště tak, aby se spouštěly místně pomocí emulátoru. Emulátor v tomto případě je Azurite. Opensourcový emulátor Azurite poskytuje bezplatné místní prostředí pro testování aplikací Azure Blob, Queue Storage a Table Storage a je to dokonalý doplněk k integraci .NET AspireAzure hostování. Azurite není nainstalovaný, místo toho je přístupný pro .NET.NET Aspire jako kontejner. Když do hostitele aplikace přidáte kontejner, jak je znázorněno v předchozím příkladu s imagí mcr.microsoft.com/azure-storage/azurite, vytvoří a spustí kontejner při spuštění hostitele aplikace. Další informace naleznete v části Životní cyklus prostředků kontejneru.

Konfigurace kontejneru Azurite

Pro prostředky kontejneru jsou k dispozici různé konfigurace, například můžete nakonfigurovat porty kontejneru, proměnné prostředí, životnostatd.

Konfigurace portů kontejneru Azurite

Ve výchozím nastavení kontejner Azurite při konfiguraci pomocí .NET.NET Aspirezveřejňuje následující koncové body:

Koncový bod	Kontejnerový přístav	Port hostitele
`blob`	10 000	dynamický
`queue`	10001	dynamický
`table`	10002	dynamický

Port, na kterém naslouchají, je ve výchozím nastavení dynamický. Po spuštění kontejneru se porty mapují na náhodný port na hostitelském počítači. Pokud chcete nakonfigurovat porty koncových bodů, zřetězte volání tvůrce zdrojů kontejneru, který poskytuje metoda RunAsEmulator, jak je znázorněno v následujícím příkladu:

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

Předchozí kód nakonfiguruje existující koncové body kontejneru Azurite: blob, queuea table, aby naslouchaly na portech 27000, 27001a 27002. Porty kontejneru Azurite se mapují na hostitelské porty, jak je znázorněno v následující tabulce:

Název koncového bodu	Mapování portů (`container:host`)
`blob`	`10000:27000`
`queue`	`10001:27001`
`table`	`10002:27002`

Konfigurace kontejneru Azurite s trvalou životností

Pokud chcete nakonfigurovat kontejner Azurite s trvalou životností, zavolejte metodu WithLifetime prostředku kontejneru Azurite a předejte 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...

Další informace naleznete v části Životnost kontejneru.

Konfigurace kontejneru Azurite s datovým svazkem

Pokud chcete přidat datový svazek do prostředku emulátoru úložiště Azure, zavolejte metodu WithDataVolume na prostředku emulátoru úložiště Azure:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Objem dat se používá k zachování dat Azurite mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /data v kontejneru Azurite a pokud není zadaný parametr name, název se naformátuje jako .azurite/{resource name}. Další informace o datových svazcích a podrobnosti o tom, proč se upřednostňují před připojení vazby, najdete v dokumentaci Docker: Svazky.

Konfigurace kontejneru Azurite s připojením datového svazku

Chcete-li přidat datovou vazbu k úložišti v emulátoru Azure, použijte metodu WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Vazby úložišť však umožňují přímý přístup a úpravy souborů na hostitelském systému, což je ideální pro vývoj a testování, kde jsou potřeba okamžité změny.

Připojení vazby dat spoléhají na systém souborů hostitelského počítače k zachování dat Azurite napříč restartováními kontejneru. Připojení datového svazku je umístěno na cestě ../Azurite/Data na hostitelském počítači vzhledem k adresáři aplikace (IDistributedApplicationBuilder.AppHostDirectory) v kontejneru Azurite. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Připojení k prostředkům úložiště

Když se host aplikace .NET.NET Aspire spustí, můžou k prostředkům úložiště přistupovat externí nástroje, jako je Azure Průzkumník služby Storage. Pokud je váš prostředek úložiště spuštěný místně pomocí Azurite, Azure Storage Explorer ho automaticky rozpozná.

Poznámka

Průzkumník služby Storage Azure rozpozná prostředky úložiště Azurite za předpokladu, že jsou použity výchozí porty. Pokud jste nakonfigurovali kontejner Azurite tak, aby používal různé porty, budete muset nakonfigurovat průzkumníka služby Azure Storage tak, aby se připojil ke správným portům.

Chcete-li se připojit k prostředku úložiště z Azure Storage Explorer, postupujte takto:

Spusťte hostitele aplikace .NET.NET Aspire.
Otevřete Průzkumníka služby Azure Storage.
Zobrazit podokno průzkumníka.
Kliknutím na odkaz Aktualizovat všechny aktualizujte seznam účtů úložiště.
Rozbalte uzel připojený k emulátoru &.
Rozbalte uzel Účty úložiště.
Jako předponu by se měl zobrazit účet úložiště s názvem vašeho prostředku:

Pomocí Průzkumníka služby Azure Storage můžete prozkoumat účet úložiště a jeho obsah. Další informace o používání průzkumníka služby Azure Storage najdete v tématu Začínáme s Průzkumníkem služby Storage.

Přidejte prostředek Azure Blob Storage

V hostitelském projektu vaší aplikace zaregistrujte integraci Azure Blob Storage tím, že zřetězíte volání AddBlobs na instanci IResourceBuilder<IAzureStorageResource> vrácenou prostřednictvím AddAzureStorage. Následující příklad ukazuje, jak přidat prostředek Azure Blob Storage s názvem storage a kontejner objektů blob s názvem blobs:

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

Předchozí kód:

Přidá úložiště pojmenované Azures identifikátorem storage.
Připojí volání k RunAsEmulator k nakonfigurování prostředku úložiště tak, aby běžel lokálně pomocí emulátoru. Emulátor v tomto případě je Azurite.
Přidá kontejner blob pojmenovaný blobs k prostředku úložiště.
Přidá zdroj blobs do ExampleProject a před zahájením projektu počká, až bude připravený.

Hostování kontrol stavu integrace

Integrace hostování Azure Storage automaticky přidává kontrolu stavu pro úložný prostředek. Přidá se jenom při spuštění jako emulátoru a ověří, že kontejner Azurite běží a že se k němu dá navázat připojení. Integrace hostování spoléhá na 📦 AspNetCore.HealthChecks.Azure. Storage.Blobs balíčku NuGet.

integrace Client

Pokud chcete začít s integrací .NET AspireAzure Blob Storageclient, nainstalujte balíček NuGet 📦Aspire.Azure.Storage.Blobs do projektu client, tedy do projektu pro aplikaci, který využívá Azure Blob Storageclient. Integrace Azure Blob Storageclient registruje instanci BlobServiceClient, kterou můžete použít k interakci s Azure Blob Storage.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Azure.Storage.Blobs

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

Přidej Azure Blob Storageclient

V souboru Program.cs projektu, který využívá client, zavolejte metodu rozšíření AddAzureBlobClient na libovolném IHostApplicationBuilder a zaregistrujte BlobServiceClient pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

builder.AddAzureBlobClient("blobs");

Poté můžete načíst instanci BlobServiceClient pomocí injekce závislostí. Například, pokud chcete získat client ze služby:

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

Konfigurace

Integrace .NET AspireAzure Blob Storage poskytuje několik možností konfigurace BlobServiceClient na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání AddAzureBlobClientzadat název připojovacího řetězce:

builder.AddAzureBlobClient("blobs");

Připojovací řetězec se pak načte z oddílu konfigurace ConnectionStrings a podporují se dva formáty připojení:

URI služby

Doporučeným přístupem je použít ServiceUri, která pracuje s vlastností AzureStorageBlobsSettings.Credential pro navázání připojení. Pokud nejsou nakonfigurované žádné přihlašovací údaje, použije se Azure.Identity.DefaultAzureCredential.

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

Připojovací řetězec

Případně lze použít připojovací řetězec Azure Storage.

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

Další informace najdete v tématu Konfigurace připojovacích řetězců Azure Storage.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireAzure Blob Storage podporuje Microsoft.Extensions.Configuration. Načte AzureStorageBlobsSettings a BlobClientOptions z konfigurace pomocí klíče Aspire:Azure:Storage:Blobs. Následující fragment kódu je příkladem souboru appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace Azure Blob StorageclientJSON viz Aspire.Azure. Storage.Blobs/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<AzureStorageBlobsSettings> configureSettings k nastavení některých nebo všech možností přímo v kódu, například pro konfiguraci kontrol stavu:

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

Můžete také nastavit BlobClientOptions pomocí delegáta Action<IAzureClientBuilder<BlobServiceClient, BlobClientOptions>> configureClientBuilder, druhého parametru AddAzureBlobClient metody. Například pro nastavení první části hlaviček User-Agent pro všechny požadavky, které tento clientvyvolá:

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

Client kontroly stavu integrace

Integrace .NET.NET Aspire ve výchozím nastavení umožňují kontroly stavu pro všechny služby. Další informace naleznete v přehledu integrací .NET.NET Aspire.

Integrace .NET AspireAzure Blob Storage:

Přidá kontrolu stavu, když je AzureStorageBlobsSettings.DisableHealthChecksfalse, která se pokusí připojit ke Azure Blob Storage.
Integruje se s HTTP koncovým bodem /health, který určuje, že všechny registrované kontroly stavu musí být úspěšné, aby byla aplikace považována za připravenou přijímat provoz.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireAzure Blob Storage používá následující kategorie protokolů:

Azure.Core
Azure.Identity

Trasování

Integrace .NET AspireAzure Blob Storage generuje následující aktivity trasování pomocí OpenTelemetry:

Azure.Storage.Blobs.BlobContainerClient

Metrika

Integrace .NET AspireAzure Blob Storage v současné době nepodporuje metriky ve výchozím nastavení kvůli omezením sady Azure SDK.

Sdílet prostřednictvím