Partager via

intégration de .NET AspireAzure Blob Storage

  • Article

inclut :intégration de l'hébergement et intégration Client

Azure Blob Storage est un service permettant de stocker de grandes quantités de données non structurées. L’intégration .NET AspireAzure Blob Storage vous permet de vous connecter à des instances de Azure Blob Storage existantes ou de créer de nouvelles instances à partir d’applications .NET.

Intégration de l’hébergement

Les modèles d'intégration de stockage .NET.NET AspireAzure modélisent les différentes ressources de stockage en tant que types suivants :

Pour accéder à ces types et API pour les exprimer, ajoutez le package NuGet 📦Aspire.Hosting.Azure.Storage dans le projet hôte de l'application .

dotnet add package Aspire.Hosting.Azure.Storage

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances des packages dans .NET applications.

Ajouter une ressource de stockage Azure

Dans votre projet hôte d’application, appelez AddAzureStorage pour ajouter et retourner un générateur de ressources de stockage Azure.

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

Lorsque vous ajoutez un AzureStorageResource à l’hôte de l’application, il expose d’autres API utiles pour ajouter Azure ressources de stockage Blob, File d’attente et Table. En d’autres termes, vous devez ajouter une AzureStorageResource avant d’ajouter l’une des autres ressources de stockage.

Important

Lorsque vous appelez AddAzureStorage, il appelle implicitement AddAzureProvisioning, ce qui ajoute la prise en charge de la génération dynamique de ressources Azure pendant le démarrage de l’application. L’application doit configurer l’abonnement et l’emplacement appropriés. Pour plus d’informations, consultez approvisionnement local : Configuration.

Génération de configuration Bicep

Si vous êtes nouveau dans le domaine de Bicep, sachez qu'il s'agit d'un langage spécifique au domaine pour définir les ressources Azure. Avec .NET.NET Aspire, vous n’avez pas besoin d’écrire Bicep manuellement, au lieu de cela, les API d’approvisionnement génèrent Bicep pour vous. Lorsque vous publiez votre application, le Bicep généré est fourni en même temps que le fichier manifeste. Lorsque vous ajoutez une ressource de stockage Azure, le Bicep suivant est généré :


Toggle Azure Stockage 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

Bicep précédent est un module qui provisionne un compte de stockage Azure avec les valeurs par défaut suivantes :

  • kind: type de compte de stockage. La valeur par défaut est StorageV2.
  • sku: référence SKU du compte de stockage. La valeur par défaut est Standard_GRS.
  • properties: propriétés du compte de stockage :
    • accessTier: niveau d’accès du compte de stockage. La valeur par défaut est Hot.
    • allowSharedKeyAccess: valeur booléenne qui indique si le compte de stockage autorise les demandes à être autorisées avec la clé d’accès du compte. La valeur par défaut est false.
    • minimumTlsVersion: version TLS minimale prise en charge pour le compte de stockage. La valeur par défaut est TLS1_2.
    • networkAcls: ACL réseau pour le compte de stockage. La valeur par défaut est { defaultAction: 'Allow' }.

En plus du compte de stockage, un conteneur d’objets blob est également provisionné.

Les attributions de rôles suivantes sont ajoutées au compte de stockage pour accorder à votre application l’accès. Pour plus d’informations, consultez les rôles intégrés Azure contrôle d’accès en fonction du rôle (Azure RBAC) :

Rôle / ID Description
Contributeur aux données de Blob de stockage
ba92f5b4-2d11-453d-a403-e96b0029c9fe		 Lisez, écrivez et supprimez des conteneurs de stockage et des blobs Azure.
Contributeur aux données de table de stockage
0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3		 Lire, écrire et supprimer les tables et les entités de stockage Azure.
Contributeur aux données de file d’attente de stockage
974c5e8b-45b9-4653-ba55-5f855dd0fb88		 Lisez, écrivez et supprimez les files de stockage Azure et les messages de file.

Bicep généré est un point de départ et peut être personnalisé pour répondre à vos besoins spécifiques.

Personnaliser l’infrastructure d’approvisionnement

Toutes les ressources .NET AspireAzure sont des sous-classes du type AzureProvisioningResource. Ce type permet de personnaliser le Bicep généré en fournissant une API fluide pour configurer les ressources Azure à l'aide de l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Par exemple, vous pouvez configurer le kind, sku, properties, etc. L’exemple suivant montre comment personnaliser la ressource de stockage Azure :

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

Code précédent :

Il existe de nombreuses autres options de configuration disponibles pour personnaliser la ressource de stockage Azure. Pour plus d’informations, consultez Azure.Provisioning.Storage.

Se connecter à un compte de stockage Azure existant

Vous disposez peut-être d’un compte de stockage Azure existant auquel vous souhaitez vous connecter. Au lieu de représenter une nouvelle ressource de stockage Azure, vous pouvez ajouter une chaîne de connexion à l’hôte de l’application. Pour ajouter une connexion à un compte de stockage Azure existant, appelez la méthode 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...

Note

Les chaînes de connexion sont utilisées pour représenter un large éventail d’informations de connexion, notamment les connexions de base de données, les répartiteurs de messages, les URI de point de terminaison et d’autres services. Dans .NET.NET Aspire nomenclature, le terme « chaîne de connexion » est utilisé pour représenter n’importe quel type d’informations de connexion.

La chaîne de connexion est configurée dans la configuration de l’hôte d’application, généralement sous secrets utilisateur, sous la section ConnectionStrings. L’hôte de l’application injecte cette chaîne de connexion en tant que variable d’environnement dans toutes les ressources dépendantes, par exemple :

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

La ressource dépendante peut accéder à la chaîne de connexion injectée en appelant la méthode GetConnectionString et en passant le nom de connexion en tant que paramètre, dans ce cas "blobs". L’API GetConnectionString est abrégée pour IConfiguration.GetSection("ConnectionStrings")[name].

Ajouter une ressource d'émulateur de stockage Azure

Pour ajouter une ressource d’émulateur de stockage Azure, chaînez un appel sur un IResourceBuilder<AzureStorageResource> à l’API RunAsEmulator :

var builder = DistributedApplication.CreateBuilder(args);

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

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

Lorsque vous appelez RunAsEmulator, il configure vos ressources de stockage pour qu’elles s’exécutent localement à l’aide d’un émulateur. L’émulateur dans ce cas est Azurite. L’émulateur open source Azurite fournit un environnement local gratuit pour tester vos applications Blob, File d’attente et Stockage Table Azure, et c’est un compagnon idéal pour l’intégration de l’hébergement .NET AspireAzure. Azurite n’est pas installé, au lieu de cela, il est accessible à .NET.NET Aspire en tant que conteneur. Lorsque vous ajoutez un conteneur à l’hôte d’application, comme illustré dans l’exemple précédent avec l’image mcr.microsoft.com/azure-storage/azurite, il crée et démarre le conteneur au démarrage de l’hôte de l’application. Pour plus d’informations, consultez cycle de vie des ressources de conteneurs.

Configurer le conteneur Azurite

Il existe différentes configurations disponibles pour les ressources de conteneur, par exemple, vous pouvez configurer les ports du conteneur, les variables d’environnement, il est durée de vie, etc.

Configurer les ports de conteneur Azurite

Par défaut, le conteneur Azurite lorsqu’il est configuré par .NET.NET Aspireexpose les points de terminaison suivants :

Point de terminaison Port de conteneur Port hôte
blob 10 000 dynamique
queue 10001 dynamique
table 10002 dynamique

Le port sur lequel ils écoutent est dynamique par défaut. Au démarrage du conteneur, les ports sont mappés à un port aléatoire sur l’ordinateur hôte. Pour configurer les ports de point de terminaison, enchaînez les appels sur le générateur de ressources de conteneur fourni par la méthode RunAsEmulator, comme indiqué dans l'exemple suivant :

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

Le code précédent configure les points de terminaison blob, queueet table existants du conteneur Azurite pour écouter sur les ports 27000, 27001et 27002, respectivement. Les ports du conteneur Azurite sont mappés aux ports hôtes, comme indiqué dans le tableau suivant :

Nom du point de terminaison Mappage de ports (container:host)
blob 10000:27000
queue 10001:27001
table 10002:27002
Configurer un conteneur Azurite avec une durée de vie persistante

Pour configurer le conteneur Azurite avec une durée de vie persistante, appelez la méthode WithLifetime sur la ressource de conteneur Azurite et transmettez 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...

Pour plus d’informations, consultez durée de vie des ressources conteneur.

Configurer un conteneur Azurite avec un volume de données

Pour ajouter un volume de données à la ressource de l’émulateur de stockage Azure, appelez la méthode WithDataVolume sur la ressource de l’émulateur de stockage Azure :

var builder = DistributedApplication.CreateBuilder(args);

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

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

Le volume de données est utilisé pour conserver les données Azurite en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin d’accès /data dans le conteneur Azurite et lorsqu’un paramètre name n’est pas fourni, le nom est mis en forme comme .azurite/{resource name}. Pour plus d'informations sur les volumes de données et pourquoi ils sont préférés aux montages de liaison , consultez la documentation Docker : Volumes.

Configurer un conteneur Azurite avec point de montage de données

Pour ajouter un montage de liaison de données à la ressource de l’émulateur de stockage Azure, appelez la méthode WithDataBindMount :

var builder = DistributedApplication.CreateBuilder(args);

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

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

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes , qui offrent de meilleures performances, une meilleure portabilité et sécurité, les rendant ainsi plus adaptés aux environnements de production. Toutefois, les liaisons de montage autorisent l’accès direct et la modification des fichiers sur le système hôte, ce qui est idéal pour le développement et le test, où les modifications en temps réel sont nécessaires.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données Azurite entre les redémarrages de conteneur. Le montage de liaison de données est monté sur le chemin d’accès ../Azurite/Data sur l’ordinateur hôte par rapport au répertoire hôte de l’application (IDistributedApplicationBuilder.AppHostDirectory) dans le conteneur Azurite. Pour plus d’informations sur les montages de liaison de données, consultez Docker docs : Liaison de montages.

Se connecter aux ressources de stockage

Lorsque l’hôte d’application .NET.NET Aspire s’exécute, les ressources de stockage sont accessibles par des outils externes, tels que l’Explorateur stockage Azure. Si votre ressource de stockage s’exécute localement à l’aide d’Azurite, elle est automatiquement récupérée par l’Explorateur stockage Azure.

Note

L’Explorateur stockage Azure découvre les ressources de stockage Azurite en supposant que les ports par défaut sont utilisés. Si vous avez configuré le conteneur Azurite pour utiliser différents ports, vous devez configurer l’Explorateur de stockage Azure pour vous connecter aux ports appropriés.

Pour vous connecter à la ressource de stockage à partir de Azure Explorateur Stockage, procédez comme suit :

  1. Exécutez l’hôte d’application .NET.NET Aspire.

  2. Ouvrez l’Explorateur stockage Azure.

  3. Affichez le volet de l’Explorateur .

  4. Sélectionnez le lien Actualiser tout afin de rafraîchir la liste des comptes de stockage.

  5. Développez le nœud attaché de l'émulateur &.

  6. Développez le nœud comptes de stockage.

  7. Vous devez voir un compte de stockage portant le nom de votre ressource comme préfixe :

    Azure Explorateur de Stockage : ressource de stockage Azurite découverte.

Vous êtes libre d’explorer le compte de stockage et son contenu à l’aide de l’Explorateur stockage Azure. Pour plus d’informations sur l’utilisation de l’Explorateur stockage Azure, consultez Prise en main de l’Explorateur Stockage.

Ajouter Azure Blob Storage ressource

Dans le projet hôte de votre application, enregistrez l’intégration Azure Blob Storage en effectuant un appel à AddBlobs sur l’instance IResourceBuilder<IAzureStorageResource> renvoyée par AddAzureStorage. L’exemple suivant montre comment ajouter une ressource Azure Blob Storage nommée storage et un conteneur d’objets blob nommé 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...

Code précédent :

  • Ajoute une ressource de stockage Azure nommée storage.
  • Chaîne un appel à RunAsEmulator pour configurer la ressource de stockage à exécuter localement à l’aide d’un émulateur. L’émulateur dans ce cas est Azurite.
  • Ajoute un conteneur d’objets blob nommé blobs à la ressource de stockage.
  • Ajoute la ressource blobs au ExampleProject et attend qu’elle soit prête avant de démarrer le projet.

Vérifications d’intégrité de l’intégration d’hébergement

L’intégration de l’hébergement de stockage Azure ajoute automatiquement un contrôle d’intégrité pour la ressource de stockage. Elle est ajoutée uniquement lors de l’exécution en tant qu’émulateur et vérifie que le conteneur Azurite est en cours d’exécution et qu’une connexion peut être établie à celui-ci. L’intégration de l’hébergement s’appuie sur le package NuGet 📦 AspNetCore.HealthChecks.Azure.Storage.Blobs.

intégration de Client

Pour commencer à utiliser l'intégration .NET AspireAzure Blob Storageclient, installez le package NuGet 📦Aspire.Azure.Storage.Blobs dans le projet consommateur client, c'est-à-dire le projet de l'application qui utilise le Azure Blob Storageclient. L’intégration Azure Blob Storageclient inscrit une instance de BlobServiceClient que vous pouvez utiliser pour interagir avec Azure Blob Storage.

dotnet add package Aspire.Azure.Storage.Blobs

Ajouter Azure Blob Storageclient

Dans le fichier Program.cs de votre projet utilisant client, appelez la méthode d'extension AddAzureBlobClient sur un IHostApplicationBuilder quelconque pour inscrire un BlobServiceClient à utiliser via le conteneur d'injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddAzureBlobClient("blobs");

Vous pouvez ensuite récupérer l’instance BlobServiceClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer le client à partir d’un service :

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

Configuration

L’intégration .NET AspireAzure Blob Storage fournit plusieurs options pour configurer l'BlobServiceClient en fonction des exigences et des conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de AddAzureBlobClient:

builder.AddAzureBlobClient("blobs");

Ensuite, la chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings, et deux formats de connexion sont pris en charge :

Service URI

L’approche recommandée consiste à utiliser un ServiceUri, qui fonctionne avec la propriété AzureStorageBlobsSettings.Credential pour établir une connexion. Si aucune information d’identification n’est configurée, la Azure.Identity.DefaultAzureCredential est utilisée.

{
  "ConnectionStrings": {
    "blobs": "https://{account_name}.blob.core.windows.net/"
  }
}
Chaîne de connexion

Vous pouvez également utiliser une chaîne de connexion de stockage Azure.

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

Pour plus d’informations, consultez Configurer des chaînes de connexion de stockage Azure.

Utiliser des fournisseurs de configuration

L’intégration .NET AspireAzure Blob Storage prend en charge Microsoft.Extensions.Configuration. Il charge les AzureStorageBlobsSettings et les BlobClientOptions depuis la configuration en utilisant la clé Aspire:Azure:Storage:Blobs. L’extrait de code suivant est un exemple de fichier appsettings.json qui configure certaines des options :

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

Pour obtenir le schéma complet Azure Blob Storageclient d’intégration JSON, consultez Aspire.Azure. Storage.Blobs/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<AzureStorageBlobsSettings> configureSettings pour paramétrer certaines ou toutes les options directement, par exemple pour effectuer des vérifications d'intégrité :

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

Vous pouvez également configurer le BlobClientOptions à l’aide du délégué Action<IAzureClientBuilder<BlobServiceClient, BlobClientOptions>> configureClientBuilder, le deuxième paramètre de la méthode AddAzureBlobClient. Par exemple, pour définir la première partie des en-têtes User-Agent pour toutes les requêtes émises par ce client:

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

Client vérifications d’intégrité de l’intégration

Par défaut, les .NET.NET Aspire intégrations activent les contrôles de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

Intégration .NET AspireAzure Blob Storage :

  • Ajoute la vérification de l'état de santé lorsque AzureStorageBlobsSettings.DisableHealthChecks est false, et tente de se connecter au Azure Blob Storage.
  • S’intègre au point de terminaison HTTP /health, qui spécifie que toutes les vérifications d’intégrité inscrites doivent réussir pour que l’application soit considérée comme prête à recevoir du trafic.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L’intégration .NET AspireAzure Blob Storage utilise les catégories de journalisation suivantes :

  • Azure.Core
  • Azure.Identity

Traçage

L’intégration .NET AspireAzure Blob Storage émet les activités de suivi suivantes à l’aide de OpenTelemetry:

  • Azure.Storage.Blobs.BlobContainerClient

Métriques

L’intégration .NET AspireAzure Blob Storage ne prend actuellement pas en charge les métriques par défaut en raison de limitations avec le KIT DE développement logiciel (SDK) Azure.

Voir aussi