intégration des tables de données .NET AspireAzure

Article
12/12/2024

inclut :intégration d’hébergement et Client intégration

Azure Table Storage est un service permettant de stocker des données NoSQL structurées. L’intégration des tables de données .NET AspireAzure vous permet de vous connecter à des instances de Azure Table Storage existantes ou de créer de nouvelles instances à partir de .NET applications.

Intégration de l’hébergement

Le .NET.NET AspireAzure Storage intègre les différentes ressources de stockage comme les types suivants :

AzureStorageResource: représente une ressource de stockage Azure.
AzureStorageEmulatorResource: représente une ressource d’émulateur de stockage Azure (Azurite).
AzureBlobStorageResource: représente une ressource de stockage blob Azure.
AzureQueueStorageResource: représente une ressource de stockage file d’attente Azure.
AzureTableStorageResource: représente une ressource de stockage table Azure.

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 .

.NET CLI
packageReference

dotnet add package Aspire.Hosting.Azure.Storage

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

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

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.

Approvisionnement généré Bicep

Si vous débutez avec Bicep, c'est un langage de domaine spécifique utilisé pour définir des 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 produit en même temps que le fichier manifeste. Lorsque vous ajoutez une ressource de stockage Azure, le Bicep suivant est généré :

Bascule 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, il configure également un conteneur de blobs.

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 de données Blob de stockage `ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Lisez, écrivez et supprimez les conteneurs et blobs de stockage 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 Azure files d’attente et messages de file d’attente de stockage.

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 la personnalisation du 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 :

Chaîne un appel à l’API ConfigureInfrastructure :
- Le paramètre infra est une instance du type AzureResourceInfrastructure.
- Les ressources provisionnables sont récupérées en appelant la méthode GetProvisionableResources().
- La seule StorageAccount est récupérée.
- La StorageAccount.AccessTier est affectée à StorageAccountAccessTier.Cool.
- Le StorageAccount.Sku est attribué à un nouveau StorageSku avec une Name de PremiumZrs.
- Une balise est ajoutée au compte de stockage avec une clé de ExampleKey et une valeur de Example value.

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 la 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 du conteneur.

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, sa durée de vie, et plus encore.

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 illustré 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 la durée de vie des ressources du 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 sur la raison pour laquelle ils sont préférés par rapport aux montages de liaison , consultez Docker documentation : Volumes.

Configurer un conteneur Azurite avec montage de liaison 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 une sécurité accrue, ce qui les rend plus adaptés aux environnements de production. Toutefois, les montages de liaison permettent un 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 lorsque des changements 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 les documents Docker : montages de liaison.

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 :

Exécutez l’hôte d’application .NET.NET Aspire.
Ouvrez l’Explorateur stockage Azure.
Affichez le volet de l’Explorateur .
Sélectionnez le lien Actualiser tout pour actualiser la liste des comptes de stockage.
Développez le nœud attaché de l’émulateur &.
Développez le nœud comptes de stockage.
Vous devez voir un compte de stockage portant le nom de votre ressource comme préfixe :

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 Table Storage ressource

Dans le projet hôte de votre application, inscrivez l’intégration Azure Table Storage en chaînant un appel à AddTables sur l’instance IResourceBuilder<IAzureStorageResource> renvoyée par AddAzureStorage. L’exemple suivant montre comment ajouter une ressource Azure Table Storage nommée storage et une ressource de table nommée tables:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Code précédent :

Ajoute une ressource de stockage Azure nommée storage.
Ajoute une ressource de stockage de table nommée tables à la ressource de stockage.
Ajoute la ressource storage 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.📦.Storage.Blobs Azure.

intégration de Client

Pour commencer à utiliser l’intégration des tables de données .NET AspireAzureclient, installez le package NuGet 📦Aspire.Azure.Data.Tables dans le projet client, c’est-à-dire celui de l’application qui utilise les tables de données Azureclient. L’intégration des Tableaux de Données Azureclient enregistre une instance TableServiceClient que vous pouvez utiliser pour interagir avec Azure Table Storage.

.NET CLI
packageReference

dotnet add package Aspire.Azure.Data.Tables

<PackageReference Include="Aspire.Azure.Data.Tables"
                  Version="*" />

Ajouter Azure Table Storageclient

Dans le fichier Program.cs de votre projet qui utilise client, appelez la méthode d'extension AddAzureTableClient sur n’importe quel IHostApplicationBuilder pour enregistrer un TableServiceClient pour utilisation via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddAzureTableClient("tables");

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

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

Configuration

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

Utiliser des fournisseurs de configuration

L’intégration .NET AspireAzure Table Storage prend en charge Microsoft.Extensions.Configuration. Il charge les AzureDataTablesSettings et les TableClientOptions à partir de la configuration à l’aide de la clé Aspire:Azure:Data:Tables. L’extrait de code suivant est un exemple de fichier appsettings.json qui configure certaines des options :

{
  "Aspire": {
    "Azure": {
      "Data": {
        "Tables": {
          "ServiceUri": "YOUR_URI",
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "EnableTenantDiscovery": true
          }
        }
      }
    }
  }
}

Pour obtenir le schéma complet Azure tables de données client l’intégration JSON, consultez Aspire.Azure. Data.Tables/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<AzureDataTablesSettings> configureSettings pour configurer certaines ou toutes les options en ligne, par exemple pour le ServiceUri:

builder.AddAzureTableClient(
    "tables",
    settings => settings.DisableHealthChecks = true);

Vous pouvez également configurer le TableClientOptions en utilisant le délégué Action<IAzureClientBuilder<TableServiceClient, TableClientOptions>> configureClientBuilder, le deuxième paramètre de la méthode AddAzureTableClient. Par exemple, pour définir l’ID de TableServiceClient pour identifier le client:

builder.AddAzureTableClient(
    "tables",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.EnableTenantDiscovery = true));

Client contrôles de santé de l’intégration

Par défaut, les intégrations .NET.NET Aspire 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 des tables de données .NET AspireAzure :

Ajout du contrôle d’intégrité lorsque AzureDataTablesSettings.DisableHealthChecks est false, qui vise à se connecter au Azure Table Storage.
S’intègre au point de terminaison HTTP /health, qui spécifie que toutes les vérifications d’intégrité enregistrées doivent réussir pour que l’application soit considérée comme prête à accepter le 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 des tableaux de données .NET AspireAzure fait appel aux catégories de journaux suivantes :

Azure.Core
Azure.Identity

Traçage

L’intégration des tables de données .NET AspireAzure émet les activités de suivi suivantes à l’aide de OpenTelemetry:

Azure.Data.Tables.TableServiceClient

Mesures

L’intégration des tables de données .NET AspireAzure ne prend actuellement pas en charge les métriques par défaut en raison de limitations avec le SDK Azure.

Partager via