Partager via

Vue d’ensemble des intégrations .NET AspireAzure

  • Article

Azure est la plateforme cloud la plus populaire pour la création et le déploiement d’applications .NET. Le SDK Azure pour .NET permet de gérer et d’utiliser facilement les services Azure. .NET Aspire fournit un ensemble d’intégrations avec Azure services, où vous êtes libre d’ajouter de nouvelles ressources ou de vous connecter à des ressources existantes. Cet article décrit certains aspects courants de toutes les intégrations Azure dans .NET Aspire et vise à vous aider à comprendre comment les utiliser.

Ajouter des ressources Azure

Toutes les intégrations d’hébergement .NET AspireAzure exposent des ressources Azure et par convention sont ajoutées à l’aide d’API AddAzure*. Lorsque vous ajoutez ces ressources à votre hôte d’application .NET Aspire, elles représentent un service Azure. L’API AddAzure* retourne une IResourceBuilder<T> où T est le type de ressource Azure. Ces interfaces IResourceBuilder<T> (générateur) fournissent une API Fluent qui vous permet de configurer la ressource Azure sous-jacente au sein du modèle d’application . Il existe des API pour ajouter de nouvelles ressources Azure, marquer les ressources comme existantes et configurer le comportement des ressources dans différents contextes d’exécution.

Expérience de développement classique

Lorsque votre hôte d’application .NET Aspire contient des ressources Azure et que vous l’exécutez localement (typiquement en utilisant la touche F5 pour les développeurs ou une expérience similaire de dotnet run), les ressources Azure sont mises en place dans votre abonnement Azure. Cela vous permet en tant que développeur de déboguer sur eux localement dans le contexte de votre hôte d’application.

.NET .NET Aspire vise à minimiser les coûts en choisissant par défaut l'option Basic ou StandardUnité de Gestion des Stocks (SKU) pour ses intégrations Azure. Bien que ces valeurs par défaut sensibles soient fournies, vous pouvez personnaliser les ressources Azure en fonction de vos besoins. En outre, certaines intégrations prennent en charge émulateurs ou conteneurs, ce qui est utile pour le développement, les tests et le débogage locaux. Par défaut, lorsque vous exécutez votre application localement, les ressources Azure utilisent le service Azure réel. Toutefois, vous pouvez les configurer pour utiliser des émulateurs ou des conteneurs locaux, ce qui évite les coûts associés au service de Azure réel pendant le développement local.

Émulateurs locaux

Certains Azure services peuvent être émulés pour s’exécuter localement. Actuellement, .NET Aspire prend en charge les émulateurs de Azure suivants :

Intégration de l’hébergement Description
Azure Cosmos DB Appelez AzureCosmosExtensions.RunAsEmulator sur le IResourceBuilder<AzureCosmosDBResource> pour configurer la ressource Cosmos DB pour qu’elle soit émulée avec l’API NoSQL.
Azure Event Hubs Appelez AzureEventHubsExtensions.RunAsEmulator sur le IResourceBuilder<AzureEventHubsResource> pour configurer la ressource Event Hubs pour qu’elle soit émulée.
Azure Service Bus Appelez AzureServiceBusExtensions.RunAsEmulator sur le IResourceBuilder<AzureServiceBusResource> pour configurer la ressource Service Bus pour qu’elle soit émulée avec l’émulateur Service Bus.
Azure SignalR Service Appelez le AzureSignalRExtensions.RunAsEmulator sur le IResourceBuilder<AzureSignalRResource> pour configurer la ressource SignalR afin qu’elle soit émulée avec l’émulateur AzureSignalR.
Azure Stockage Appelez AzureStorageExtensions.RunAsEmulator sur le IResourceBuilder<AzureStorageResource> pour configurer la ressource de stockage pour qu’elle soit émulée avec Azurite.

Pour que vos ressources Azure utilisent les émulateurs locaux, chaînez un appel à la méthode RunAsEmulator sur le générateur de ressources Azure. Cette méthode configure la ressource Azure pour utiliser l’émulateur local au lieu du service Azure réel.

Important

L’appel de l’une des API RunAsEmulator disponibles sur un générateur de ressources Azure n’affecte pas le manifeste de publication . Lorsque vous publiez votre application, le fichier Bicep généré reflète le service Azure réel, pas l’émulateur local.

Conteneurs locaux

Certaines ressources Azure peuvent être substituées localement à l’aide de conteneurs open source ou locaux. Pour remplacer une ressource Azure localement dans un conteneur, chaînez un appel à la méthode RunAsContainer sur le générateur de ressources Azure. Cette méthode configure la ressource Azure pour utiliser une version conteneurisée du service pour le développement et les tests locaux, plutôt que le service de Azure réel.

Actuellement, .NET Aspire prend en charge les services de Azure suivants en tant que conteneurs :

Intégration de l’hébergement Détails
Azure Cache for Redis Appelez AzureRedisExtensions.RunAsContainer sur le IResourceBuilder<AzureRedisCacheResource> pour le configurer pour qu’il s’exécute localement dans un conteneur, en fonction de l’image docker.io/library/redis.
Azure PostgreSQL Server flexible Appelez AzurePostgresExtensions.RunAsContainer sur le IResourceBuilder<AzurePostgresFlexibleServerResource> pour le configurer pour qu’il s’exécute localement dans un conteneur, en fonction de l’image docker.io/library/postgres.
Azure SQL Server Appelez AzureSqlExtensions.RunAsContainer sur le IResourceBuilder<AzureSqlServerResource> pour le configurer pour qu’il s’exécute localement dans un conteneur, en fonction de l’image mcr.microsoft.com/mssql/server.

Remarque

Comme les émulateurs, l'appel à RunAsContainer sur un générateur de ressources Azure ne produit aucun effet sur le manifeste de publication . Lorsque vous publiez votre application, le fichier Bicep généré reflète le service Azure réel, plutôt que le conteneur local.

Comprendre les API d’intégration Azure

.NET .NET Aspirela force réside dans sa capacité à fournir une boucle interne de développeur incroyable. Les intégrations Azure ne sont pas différentes. Ils fournissent un ensemble d’API et de modèles communs qui sont partagés entre toutes les ressources Azure. Ces API et modèles sont conçus pour faciliter l’utilisation de ressources Azure de manière cohérente.

Dans la section précédente sur les conteneurs, vous avez vu comment exécuter des services Azure localement dans des conteneurs. Si vous connaissez .NET.NET Aspire, vous pouvez vous demander comment appeler AddAzureRedis("redis").RunAsContainer() pour obtenir un conteneur docker.io/library/redis local diffère de AddRedis("redis"), car ils entraînent tous les deux le même conteneur local.

La réponse est qu’il n’existe aucune différence lors de l’exécution locale. Toutefois, lorsqu’ils sont publiés, vous obtenez différentes ressources :

API Mode d’exécution Mode de publication
AddAzureRedis(« redis »).RunAsContainer() Conteneur Redis local Azure Cache for Redis
addRedis(« redis ») Conteneur Redis local Application de conteneur Azure avec l'image Redis

Il en va de même pour les services SQL et PostgreSQL :

API Mode d’exécution Mode de publication
AddAzurePostgresFlexibleServer(« postgres »). RunAsContainer() Conteneur PostgreSQL local Azure PostgreSQL Server flexible
AddPostgres(« postgres ») Conteneur PostgreSQL local Application de conteneur Azure avec l'image PostgreSQL
AddAzureSqlServer(« sql »).RunAsContainer() Conteneur SQL Server local Azure SQL Server
AddSqlServer(« sql ») Conteneur SQL Server local Application conteneur Azure avec image SQL Server

Pour plus d’informations sur la différence entre les modes d’exécution et de publication, consultez .NET.NET Aspire'hôte d’application : contexte d’exécution.

API pour exprimer des ressources Azure dans différents modes

Le générateur d’applications distribuées, qui fait partie de l’hôte d’application , utilise le modèle de générateur pour AddAzure* ressources au modèle d’application . Les développeurs peuvent configurer ces ressources et définir leur comportement dans différents contextes d’exécution. Les intégrations d’hébergement Azure fournissent des API pour spécifier la façon dont ces ressources doivent être « publiées » et « exécutées ».

Lorsque l’hôte de l’application s’exécute, le contexte d’exécution est utilisé pour déterminer si l’hôte de l’application est en mode Run ou Publish. Les conventions d’affectation de noms pour ces API indiquent l’action prévue pour la ressource.

Le tableau suivant récapitule les conventions d’affectation de noms utilisées pour exprimer des ressources Azure :

Opération Interface de Programmation d'Application (API) Description
Publier PublishAsConnectionString<T>(IResourceBuilder<T>) Modifie la ressource à publier en tant que référence de chaîne de connexion dans le manifeste.
Publier PublishAsExisting Utilise une ressource Azure existante lorsque l’application est déployée au lieu de en créer une nouvelle.
Courir AzureSqlExtensions.RunAsContainer(IResourceBuilder<AzureSqlServerResource>, Action<IResourceBuilder<SqlServerServerResource>>)
AzureRedisExtensions.RunAsContainer(IResourceBuilder<AzureRedisCacheResource>, Action<IResourceBuilder<RedisResource>>)
RunAsContainer(IResourceBuilder<AzurePostgresFlexibleServerResource>, Action<IResourceBuilder<PostgresServerResource>>)		 Configure un conteneur équivalent à exécuter localement. Pour plus d’informations, consultez les conteneurs locaux .
Courir AzureCosmosExtensions.RunAsEmulator(IResourceBuilder<AzureCosmosDBResource>, Action<IResourceBuilder<AzureCosmosDBEmulatorResource>>)
AzureSignalRExtensions.RunAsEmulator(IResourceBuilder<AzureSignalRResource>, Action<IResourceBuilder<AzureSignalREmulatorResource>>)
AzureStorageExtensions.RunAsEmulator(IResourceBuilder<AzureStorageResource>, Action<IResourceBuilder<AzureStorageEmulatorResource>>)
AzureEventHubsExtensions.RunAsEmulator(IResourceBuilder<AzureEventHubsResource>, Action<IResourceBuilder<AzureEventHubsEmulatorResource>>)
AzureServiceBusExtensions.RunAsEmulator(IResourceBuilder<AzureServiceBusResource>, Action<IResourceBuilder<AzureServiceBusEmulatorResource>>)		 Configure la ressource Azure à émuler. Pour plus d’informations, consultez émulateurs locaux.
Courir RunAsExisting Utilise une ressource existante lorsque l’application est en cours d’exécution au lieu de en créer une nouvelle.
Publier et exécuter AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) Utilise une ressource existante, quelle que soit l’opération.

Note

Toutes les API ne sont pas disponibles sur toutes les ressources Azure. Par exemple, certaines ressources Azure peuvent être conteneurisées ou émulées, tandis que d’autres ne peuvent pas.

Pour plus d’informations sur les modes d’exécution, consultez contexte d’exécution.

Cas d’utilisation de l’API en mode exécution général

Utilisez RunAsExisting lorsque vous devez interagir dynamiquement avec une ressource existante pendant l’exécution sans avoir à la déployer ou à la mettre à jour. Utilisez PublishAsExisting lors de la déclaration de ressources existantes dans le cadre d’une configuration de déploiement, en veillant à ce que les étendues et autorisations appropriées soient appliquées. Enfin, utilisez AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) lors de la déclaration de ressources existantes dans les deux configurations, avec une exigence pour paramétrer les références.

Vous pouvez interroger si une ressource est marquée comme une ressource existante, en appelant la méthode d’extension IsExisting(IResource) sur le IResource. Pour plus d’informations, consultez Utilisation des ressources Azure existantes.

Utiliser des ressources Azure existantes

.NET Aspire prend en charge le référencement des ressources Azure existantes. Vous marquez une ressource existante via les API PublishAsExisting, RunAsExistinget AsExisting. Ces API permettent aux développeurs de référencer des ressources Azure déjà déployées, de les configurer et de générer des manifestes de déploiement appropriés à l’aide de modèles Bicep.

Les ressources existantes référencées par ces API peuvent être améliorées par des attributions de rôles et d'autres personnalisations disponibles grâce aux capacités d'infrastructure en tant que code de .NET.NET Aspire. Ces API sont limitées aux ressources Azure qui peuvent être déployées avec des modèles Bicep.

Configurer des ressources Azure existantes pour le mode d’exécution

La méthode RunAsExisting est utilisée lorsqu’une application distribuée s’exécute en mode « Exécuter ». Dans ce mode, il part du principe que la ressource Azure référencée existe déjà et s’intègre à celle-ci pendant l’exécution sans provisionner la ressource. Pour marquer une ressource Azure comme étant existante, appelez la méthode RunAsExisting sur le générateur de ressources. Prenons l’exemple suivant :

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Code précédent :

  • Crée une nouvelle instance builder.
  • Ajoute un paramètre nommé existingServiceBusName au générateur.
  • Ajoute une ressource Azure Service Bus nommée messaging au générateur.
  • Appelle la méthode RunAsExisting sur le générateur de ressources serviceBus, en passant le paramètre existingServiceBusName. Vous pouvez également utiliser la surcharge de paramètre string.
  • Ajoute une file d’attente nommée queue à la ressource serviceBus.

Par défaut, la référence de paramètre Service Bus est supposée se trouver dans le même groupe de ressources Azure. Toutefois, s’il se trouve dans un autre groupe de ressources, vous pouvez transmettre explicitement le groupe de ressources en tant que paramètre pour spécifier correctement le regroupement de ressources approprié.

Configurer des ressources Azure existantes pour le mode de publication

La méthode PublishAsExisting est utilisée en mode « publier » lorsque l’intention est de déclarer et de référencer une ressource Azure déjà existante pendant le mode de publication. Cette API facilite la création de manifestes et de modèles qui incluent des définitions de ressources mappées aux ressources existantes dans Bicep.

Pour marquer une ressource Azure comme étant existante pour le mode « publier », appelez la méthode PublishAsExisting sur le générateur de ressources. Prenons l’exemple suivant :

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .PublishAsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Code précédent :

  • Crée une nouvelle instance builder.
  • Ajoute un paramètre nommé existingServiceBusName au générateur.
  • Ajoute une ressource Azure Service Bus nommée messaging au générateur.
  • Appelle la méthode PublishAsExisting sur le générateur de ressources serviceBus, en passant le paramètre existingServiceBusName. Vous pouvez également utiliser la surcharge de paramètre string.
  • Ajoute une file d’attente nommée queue à la ressource serviceBus.

Une fois l’hôte d’application exécuté en mode publication, le fichier manifeste généré inclut le paramètre existingResourceName, qui peut être utilisé pour référencer la ressource Azure existante. Tenez compte de l’extrait de code partiel généré suivant du fichier manifeste :

"messaging": {
  "type": "azure.bicep.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}",
  "path": "messaging.module.bicep",
  "params": {
    "existingServiceBusName": "{existingServiceBusName.value}",
    "principalType": "",
    "principalId": ""
  }
},
"queue": {
  "type": "value.v0",
  "connectionString": "{messaging.outputs.serviceBusEndpoint}"
}

Pour plus d’informations sur le fichier manifeste, consultez .NET.NET Aspire format de manifeste pour les générateurs d’outils de déploiement.

En outre, le modèle Bicep généré inclut le paramètre existingResourceName, qui peut être utilisé pour référencer la ressource Azure existante. Tenez compte du modèle Bicep généré suivant :

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

param existingServiceBusName string

param principalType string

param principalId string

resource messaging 'Microsoft.ServiceBus/namespaces@2024-01-01' existing = {
  name: existingServiceBusName
}

resource messaging_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(messaging.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: messaging
}

resource queue 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = {
  name: 'queue'
  parent: messaging
}

output serviceBusEndpoint string = messaging.properties.serviceBusEndpoint

Pour plus d’informations sur les modèles Bicep générés, consultez Infrastructure en tant que code et envisagez d’autres API de publication.

Avertissement

Lors de l’interaction avec les ressources existantes qui nécessitent l’authentification, assurez-vous que la stratégie d’authentification que vous configurez dans le modèle d’application .NET.NET Aspire s’aligne sur la stratégie d’authentification autorisée par la ressource existante. Par exemple, il n’est pas possible d’utiliser une identité managée par rapport à une ressource AzurePostgreSQL existante qui n’est pas configurée pour autoriser l’identité managée. De même, si une ressource AzureRedis existante a désactivé les clés d’accès, il n’est pas possible d’utiliser l’authentification par clé d’accès.

Configurer des ressources Azure existantes dans tous les modes

La méthode AsExisting<T>(IResourceBuilder<T>, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>) est utilisée lorsque l’application distribuée s’exécute en mode « exécuter » ou « publier ». Étant donné que la méthode AsExisting fonctionne dans les deux scénarios, elle prend uniquement en charge une référence paramétrable au nom de la ressource ou au nom du groupe de ressources. Cette approche permet d’empêcher l’utilisation de la même ressource dans les environnements de test et de production.

Pour marquer une ressource Azure comme étant existante, appelez la méthode AsExisting sur le générateur de ressources. Prenons l’exemple suivant :

var builder = DistributedApplication.CreateBuilder();

var existingServiceBusName = builder.AddParameter("existingServiceBusName");
var existingServiceBusResourceGroup = builder.AddParameter("existingServiceBusResourceGroup");

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);

serviceBus.AddServiceBusQueue("queue");

Code précédent :

  • Crée une nouvelle instance builder.
  • Ajoute un paramètre nommé existingServiceBusName au générateur.
  • Ajoute une ressource Azure Service Bus nommée messaging au générateur.
  • Appelle la méthode AsExisting sur le générateur de ressources serviceBus, en passant le paramètre existingServiceBusName.
  • Ajoute une file d’attente nommée queue à la ressource serviceBus.

Ajouter des ressources Azure existantes avec des chaînes de connexion

.NET .NET Aspire permet de se connecter aux ressources existantes, y compris les ressources Azure. L’expression de chaînes de connexion est utile lorsque vous disposez de ressources Azure existantes que vous souhaitez utiliser dans votre application .NET Aspire. L’API AddConnectionString est utilisée avec le contexte d’exécution de l’hôte d’application pour ajouter de manière conditionnelle une chaîne de connexion au modèle d’application.

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.

Prenons l'exemple suivant où, en mode de publication , vous ajoutez une ressource de stockage Azure, tandis qu'en mode d'exécution , vous ajoutez une chaîne de connexion à un stockage Azure existant :

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureStorage("storage")
    : builder.AddConnectionString("storage");

builder.AddProject<Projects.Api>("api")
       .WithReference(storage);

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

Code précédent :

  • Crée une nouvelle instance builder.
  • Ajoute une ressource de stockage Azure nommée storage en mode « publier ».
  • Ajoute une chaîne de connexion à un stockage Azure existant nommé storage en mode « Exécuter ».
  • Ajoute un projet nommé api au générateur.
  • Le projet api fait référence à la ressource storage quel que soit le mode.

Le projet d’API consommant utilise les informations de chaîne de connexion sans connaître la façon dont l’hôte de l’application l’a configuré. En mode « publier », le code ajoute une nouvelle ressource de stockage Azure, qui serait reflétée dans le manifeste de déploiement en conséquence. En mode « Exécuter », la chaîne de connexion correspond à une valeur de configuration visible pour l’hôte de l’application. Il est supposé que toutes les attributions de rôles pour la ressource cible sont configurées. Cela signifie que vous configurez probablement une variable d’environnement ou un secret utilisateur pour stocker la chaîne de connexion. La configuration est résolue à partir de la clé de configuration ConnectionStrings__storage (ou ConnectionStrings:storage). Ces valeurs de configuration peuvent être consultées lorsque l’application s’exécute. Pour plus d’informations, consultez les détails des ressources .

Contrairement aux ressources existantes modélisées avec l’API de première classe AsExisting, les ressources existantes modélisées en tant que chaînes de connexion ne peuvent pas être améliorées avec des attributions de rôles supplémentaires ou des personnalisations d’infrastructure.

Publier en tant qu’application conteneur Azure

.NET .NET Aspire vous permet de publier des ressources primitives en tant que Azure Container Apps, une plateforme serverless qui réduit la gestion de l’infrastructure. Les types de ressources pris en charge comprennent :

Pour publier ces ressources, utilisez les API suivantes :

Ces API configurent la ressource à publier en tant qu’application conteneur Azure et appellent implicitement AddAzureContainerAppsInfrastructure(IDistributedApplicationBuilder) pour ajouter les fichiers Bicep et infrastructure nécessaires à votre hôte d’application. Prenons l’exemple de code suivant :

var builder = DistributedApplication.CreateBuilder();

var env = builder.AddParameter("env");

var api = builder.AddProject<Projects.AspireApi>("api")
                 .PublishAsAzureContainerApp<Projects.AspireApi>((infra, app) =>
                 {
                     app.Template.Containers[0].Value!.Env.Add(new ContainerAppEnvironmentVariable
                     {
                         Name = "Hello",
                         Value = env.AsProvisioningParameter(infra)
                     });
                 });

Code précédent :

  • Crée une nouvelle instance builder.
  • Ajoute un paramètre nommé env au générateur.
  • Ajoute un projet nommé api au générateur.
  • Appelle la méthode PublishAsAzureContainerApp sur le générateur de ressources api, en passant une expression lambda qui configure l’infrastructure Azure Container App, où infra est la AzureResourceInfrastructure et app est la ContainerApp.
    • Ajoute une variable d’environnement nommée Hello à l’application conteneur à l’aide du paramètre env.
    • La méthode AsProvisioningParameter est utilisée pour traiter env comme une nouvelle ProvisioningParameter dans l’infrastructure ou réutilise un paramètre bicep existant s’il en existe déjà un avec le même nom.

Pour plus d’informations, consultez ContainerApp et AsProvisioningParameter.

Infrastructure en tant que code

Le Kit de développement logiciel (SDK) Azure pour .NET fournit le package NuGet 📦Azure.Provisioning et une suite de packages d'approvisionnement spécifiques aux services Azure. Ces bibliothèques d’approvisionnement Azure facilitent la spécification déclarative de l’infrastructure Azure en mode natif dans .NET. Leurs API vous permettent d’écrire une infrastructure orientée objet en C#, ce qui aboutit à Bicep. Bicep est un langage spécifique au domaine (DSL) pour le déploiement de ressources Azure de manière déclarative.

Bien qu’il soit possible de provisionner Azure ressources manuellement, .NET Aspire simplifie le processus en fournissant un ensemble d’API pour exprimer des ressources Azure. Ces API sont disponibles en tant que méthodes d’extension dans .NET AspireAzure bibliothèques d’hébergement, en étendant l’interface IDistributedApplicationBuilder. Lorsque vous ajoutez les ressources Azure à l'hôte de l'application, elles ajoutent implicitement la fonctionnalité d'approvisionnement appropriée. En d’autres termes, vous n’avez pas besoin d’appeler directement des API d’approvisionnement.

Étant donné que .NET Aspire modélise les ressources Azure au sein des intégrations d’hébergement Azure, le SDK Azure est utilisé pour fournir ces ressources. Les fichiers Bicep générés définissent les ressources Azure nécessaires. Les fichiers Bicep générés sont générés en même temps que le fichier manifeste lorsque vous publiez votre application.

Il existe plusieurs façons d’influencer les fichiers Bicep générés :

Approvisionnement local et Azure.Provisioning

Pour éviter la confusion des termes et aider à désambiguïser le « provisionnement », il est important de comprendre la distinction entre le provisionnement local et le provisionnement Azure:

  • approvisionnement local :

    Par défaut, lorsque vous appelez l’une des API d’intégration d’hébergement Azure pour ajouter des ressources Azure, l’API AddAzureProvisioning(IDistributedApplicationBuilder) est appelée implicitement. Cette API inscrit des services dans le conteneur d’injection de dépendances (DI) utilisé pour approvisionner des ressources Azure lorsque l’hôte de l’application démarre. Ce concept est appelé approvisionnement local. Pour plus d'informations, consultez Provisionnement local Azure.

  • Azure.Provisioning:

    Azure.Provisioning fait référence au package NuGet et est un ensemble de bibliothèques qui vous permettent d’utiliser C# pour générer Bicep. Les intégrations d'hébergement Azure dans .NET Aspire utilisent ces bibliothèques en arrière-plan pour générer des fichiers Bicep qui définissent les ressources Azure dont vous avez besoin. Pour plus d’informations, consultez Azure.Provisioningpersonnalisation.

Personnalisation Azure.Provisioning

Toutes les intégrations d’hébergement .NET AspireAzure exposent diverses ressources Azure, et elles sont toutes des sous-classes du type AzureProvisioningResource, qui hérite elle-même de l'AzureBicepResource. Cela permet aux extensions qui sont limitées de façon générique à ce type, permettant ainsi à une API fluide de personnaliser l’infrastructure à votre guise. Bien que .NET.NET Aspire fournit des valeurs par défaut, vous êtes libre d’influencer le Bicep généré à l’aide de ces API.

Configurer l’infrastructure

Quelle que soit la ressource Azure avec laquelle vous travaillez, pour configurer son infrastructure sous-jacente, vous chaînez un appel à la méthode d’extension ConfigureInfrastructure. Cette méthode vous permet de personnaliser l’infrastructure de la ressource Azure en passant un délégué configure de type Action<AzureResourceInfrastructure>. Le type AzureResourceInfrastructure est une sous-classe du Azure.Provisioning.Infrastructure. Ce type expose une surface d’aire d’API massive pour la configuration de l’infrastructure sous-jacente de la ressource Azure.

Prenons l’exemple suivant :

var sku = builder.AddParameter("storage-sku");

var storage = builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources();

        var storageAccount = resources.OfType<StorageAccount>().Single();

        storageAccount.Sku = new StorageSku
        {
            Name = sku.AsProvisioningParameter(infra)
        };
    });

Code précédent :

  • Ajoute un paramètre nommé storage-sku.
  • Ajoute le stockage Azure avec l'API nommée AddAzureStoragestorage.
  • Chaîne un appel à ConfigureInfrastructure pour personnaliser l’infrastructure de stockage Azure :

Cela illustre le flux d’un paramètre externe dans l’infrastructure de stockage Azure, ce qui entraîne le fichier Bicep généré reflétant la configuration souhaitée.

Ajouter une infrastructure Azure

Tous les services Azure ne sont pas nécessairement présentés en tant qu'intégrations .NET Aspire. Bien qu'ils puissent être disponibles plus tard, vous pouvez toujours fournir des services disponibles dans les bibliothèques Azure.Provisioning.*. Imaginez un scénario dans lequel vous avez un service de travail responsable de la gestion d’un registre de conteneurs Azure. Imaginez maintenant qu’un projet hôte d’application dépend du package NuGet 📦Azure.Provisioning.ContainerRegistry.

Vous pouvez utiliser l’API AddAzureInfrastructure pour ajouter l’infrastructure Azure Container Registry à votre hôte d’application :

var acr = builder.AddAzureInfrastructure("acr", infra =>
{
    var registry = new ContainerRegistryService("acr")
    {
        Sku = new()
        {
            Name = ContainerRegistrySkuName.Standard
        },
    };
    infra.Add(registry);

    var output = new ProvisioningOutput("registryName", typeof(string))
    {
        Value = registry.Name
    };
    infra.Add(output);
});

builder.AddProject<Projects.WorkerService>("worker")
       .WithEnvironment(
            "ACR_REGISTRY_NAME",
            new BicepOutputReference("registryName", acr.Resource));

Code précédent :

  • Appelle AddAzureInfrastructure sous le nom de acr.
  • Fournit un délégué configureInfrastructure pour personnaliser l'infrastructure Azure du registre de conteneurs :
    • Instancie un ContainerRegistryService avec le nom acr et un SKU standard.
    • Ajoute le service Azure Container Registry à la variable infra.
    • Instancie un ProvisioningOutput avec le nom registryName, un type de stringet une valeur qui correspond au nom du registre de conteneurs Azure.
    • Ajoute la valeur de sortie à la variable infra.
  • Ajoute un projet nommé worker au générateur.
  • Enchaîne un appel à WithEnvironment pour affecter à la variable d’environnement ACR_REGISTRY_NAME du projet la valeur de la sortie registryName.

La fonctionnalité montre comment ajouter l'infrastructure Azure à votre projet d'application hôte, même si le service Azure n’est pas directement exposé en tant qu’intégration .NET Aspire. Il montre également comment transmettre la sortie du registre de conteneurs Azure dans l’environnement d’un projet dépendant.

Considérez le fichier Bicep résultant :

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

resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
  name: take('acr${uniqueString(resourceGroup().id)}', 50)
  location: location
  sku: {
    name: 'Standard'
  }
}

output registryName string = acr.name

Le fichier Bicep reflète la configuration souhaitée du registre de conteneurs Azure, tel que défini par l’API AddAzureInfrastructure.

Utiliser des modèles Bicep personnalisés

Lorsque vous ciblez Azure en tant que fournisseur de cloud souhaité, vous pouvez utiliser Bicep pour définir votre infrastructure en tant que code. Il vise à simplifier considérablement l’expérience de création avec une syntaxe plus propre et une meilleure prise en charge de la modularité et de la réutilisation du code.

Bien que .NET.NET Aspire fournit un ensemble de modèles Bicep prédéfinis, il peut arriver que vous souhaitiez personnaliser les modèles ou créer vos propres modèles. Cette section explique les concepts et les API correspondantes que vous pouvez utiliser pour personnaliser les modèles Bicep.

Important

Cette section n’est pas destinée à vous apprendre à Bicep, mais plutôt à fournir des conseils sur la création de modèles Bicep personnalisés à utiliser avec .NET.NET Aspire.

Dans le cadre du récit de déploiement de Azure pour .NET Aspire, le Azure Developer CLI (azd) fournit une compréhension de votre projet de .NET Aspire et la possibilité de le déployer sur Azure. L’interface CLI azd utilise les modèles Bicep pour déployer l’application sur Azure.

Installez le paquet Aspire.Hosting.Azure

Lorsque vous souhaitez référencer des fichiers Bicep, il est possible que vous n’utilisiez aucune des intégrations d’hébergement de Azure. Dans ce cas, vous pouvez toujours référencer des fichiers Bicep en installant le package Aspire.Hosting.Azure. Ce package fournit les API nécessaires pour référencer les fichiers Bicep et personnaliser les ressources Azure.

Pourboire

Si vous utilisez l’une des intégrations d’hébergement Azure, vous n’avez pas besoin d’installer le package Aspire.Hosting.Azure, car il s’agit d’une dépendance transitive.

Pour utiliser l’une de ces fonctionnalités, le package NuGet 📦Aspire.Hosting.Azure doit être installé :

dotnet add package Aspire.Hosting.Azure

Pour plus d’informations, consultez dotnet add package ou Manage package dependencies in .NET applications.

Ce qu’il faut attendre des exemples

Tous les exemples de cette section supposent que vous utilisez l’espace de noms Aspire.Hosting.Azure. En outre, les exemples supposent que vous disposez d’une instance de IDistributedApplicationBuilder :

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

// Examples go here...

builder.Build().Run();

Par défaut, lorsque vous appelez l’une des API liées à Bicep, un appel est également effectué pour AddAzureProvisioning qui ajoute la prise en charge de la génération dynamique de ressources Azure pendant le démarrage de l’application. Pour plus d’informations, consultez provisionnement local et Azure.Provisioning.

Référencer les fichiers Bicep

Imaginez que vous disposez d’un modèle Bicep dans un fichier nommé storage.bicep qui provisionne un compte de stockage Azure :

param location string = resourceGroup().location
param storageAccountName string = 'toylaunch${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Pour ajouter une référence au fichier Bicep sur le disque, appelez la méthode AddBicepTemplate. Prenons l’exemple suivant :

builder.AddBicepTemplate(
    name: "storage",
    bicepFile: "../infra/storage.bicep");

Le code précédent ajoute une référence à un fichier Bicep situé à ../infra/storage.bicep. Les chemins d’accès aux fichiers doivent être relatifs au projet de l’hôte de l’application . Cette référence entraîne l’ajout d’une AzureBicepResource à la collection de ressources de l’application avec le nom "storage", et l’API retourne une instance IResourceBuilder<AzureBicepResource> qui peut être utilisée pour personnaliser davantage la ressource.

Référencer Bicep en ligne

Bien qu'avoir un fichier Bicep sur disque soit le scénario le plus courant, vous pouvez également ajouter des modèles Bicep en ligne. Les modèles inline peuvent être utiles lorsque vous souhaitez définir un modèle dans le code ou lorsque vous souhaitez générer le modèle de manière dynamique. Pour ajouter un modèle Bicep inline, appelez la méthode AddBicepTemplateString avec le modèle Bicep en tant que string. Prenons l’exemple suivant :

builder.AddBicepTemplateString(
        name: "ai",
        bicepContent: """
        @description('That name is the name of our application.')
        param cognitiveServiceName string = 'CognitiveService-${uniqueString(resourceGroup().id)}'

        @description('Location for all resources.')
        param location string = resourceGroup().location

        @allowed([
          'S0'
        ])
        param sku string = 'S0'

        resource cognitiveService 'Microsoft.CognitiveServices/accounts@2021-10-01' = {
          name: cognitiveServiceName
          location: location
          sku: {
            name: sku
          }
          kind: 'CognitiveServices'
          properties: {
            apiProperties: {
              statisticsEnabled: false
            }
          }
        }
        """
    );

Dans cet exemple, le modèle Bicep est défini en tant que string inline et ajouté à la collection de ressources de l’application avec le nom "ai". Cet exemple provisionne une ressource d'intelligence artificielle Azure.

Passer des paramètres aux modèles Bicep

Bicep prend en charge l’acceptation des paramètres, qui peuvent être utilisés pour personnaliser le comportement du modèle. Pour passer des paramètres à un modèle Bicep à partir de .NET.NET Aspire, chaînez des appels à la méthode WithParameter, comme indiqué dans l’exemple suivant :

var region = builder.AddParameter("region");

builder.AddBicepTemplate("storage", "../infra/storage.bicep")
       .WithParameter("region", region)
       .WithParameter("storageName", "app-storage")
       .WithParameter("tags", ["latest","dev"]);

Code précédent :

  • Ajoute un paramètre nommé "region" à l’instance de builder.
  • Ajoute une référence à un fichier Bicep situé à ../infra/storage.bicep.
  • Transmet le paramètre "region" au modèle Bicep, qui est résolu en utilisant la résolution standard des paramètres.
  • Transmet le paramètre au modèle Bicep avec une valeur fixe.
  • Transmet le paramètre "tags" au modèle Bicep avec un tableau de chaînes.

Pour plus d’informations, consultez paramètres externes.

Paramètres connus

.NET .NET Aspire fournit un ensemble de paramètres connus qui peuvent être passés aux modèles Bicep. Ces paramètres sont utilisés pour fournir des informations sur l’application et l’environnement aux modèles Bicep. Les paramètres connus suivants sont disponibles :

Champ Description Valeur
AzureBicepResource.KnownParameters.KeyVaultName Le nom de la ressource du Key Vault utilisée pour stocker les résultats secrets. "keyVaultName"
AzureBicepResource.KnownParameters.Location Emplacement de la ressource. Cette opération est requise pour toutes les ressources. "location"
AzureBicepResource.KnownParameters.LogAnalyticsWorkspaceId ID de ressource de l'espace de travail de Log Analytics. "logAnalyticsWorkspaceId"
AzureBicepResource.KnownParameters.PrincipalId ID principal de l’utilisateur actuel ou de l’identité managée. "principalId"
AzureBicepResource.KnownParameters.PrincipalName Nom principal de l’utilisateur actuel ou de l’identité managée. "principalName"
AzureBicepResource.KnownParameters.PrincipalType Type principal de l’utilisateur actuel ou de l’identité managée. User ou ServicePrincipal. "principalType"

Pour utiliser un paramètre connu, passez le nom du paramètre à la méthode WithParameter, par exemple WithParameter(AzureBicepResource.KnownParameters.KeyVaultName). Vous ne transmettez pas de valeurs pour les paramètres connus, car .NET.NET Aspire les résout en votre nom.

Prenons un exemple dans lequel vous souhaitez configurer un webhook Event Grid Azure. Vous pouvez définir le modèle Bicep comme suit :

param topicName string
param webHookEndpoint string
param principalId string
param principalType string
param location string = resourceGroup().location

// The topic name must be unique because it's represented by a DNS entry. 
// must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and "-".

resource topic 'Microsoft.EventGrid/topics@2023-12-15-preview' = {
  name: toLower(take('${topicName}${uniqueString(resourceGroup().id)}', 50))
  location: location

  resource eventSubscription 'eventSubscriptions' = {
    name: 'customSub'
    properties: {
      destination: {
        endpointType: 'WebHook'
        properties: {
          endpointUrl: webHookEndpoint
        }
      }
    }
  }
}

resource EventGridRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(topic.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7'))
  scope: topic
  properties: {
    principalId: principalId
    principalType: principalType
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'd5a91429-5739-47e2-a06b-3470a27159e7')
  }
}

output endpoint string = topic.properties.endpoint

Ce modèle Bicep définit plusieurs paramètres, notamment les topicName, les webHookEndpoint, les principalId, les principalTypeet les locationfacultatifs. Pour passer ces paramètres au modèle Bicep, vous pouvez utiliser l’extrait de code suivant :

var webHookApi = builder.AddProject<Projects.WebHook_Api>("webhook-api");

var webHookEndpointExpression = ReferenceExpression.Create(
        $"{webHookApi.GetEndpoint("https")}/hook");

builder.AddBicepTemplate("event-grid-webhook", "../infra/event-grid-webhook.bicep")
       .WithParameter("topicName", "events")
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalId)
       .WithParameter(AzureBicepResource.KnownParameters.PrincipalType)
       .WithParameter("webHookEndpoint", () => webHookEndpointExpression);
  • Le projet webHookApi est ajouté comme référence au builder.
  • Le paramètre topicName reçoit une valeur de nom codée en dur.
  • Le paramètre webHookEndpoint est passé en tant qu’expression qui se résout à l’URL à partir du point de terminaison « https » du projet api avec l’itinéraire /hook.
  • Les paramètres principalId et principalType sont passés en tant que paramètres connus.

Les paramètres connus sont basés sur des conventions et ne doivent pas être accompagnés d’une valeur correspondante lors de l’utilisation de l’API WithParameter. Les paramètres connus simplifient certaines fonctionnalités courantes, telles que les attributions de rôles , lorsqu’elles sont ajoutées aux modèles Bicep, comme illustré dans l’exemple précédent. Les attributions de rôles sont requises pour que le webhook Event Grid envoie des événements au point de terminaison spécifié. Pour plus d’informations, consultez attribution de rôle Expéditeur de données Event Grid.

Obtenez les résultats des références de Bicep

En plus de passer des paramètres à des modèles Bicep, vous pouvez également obtenir des sorties à partir des modèles Bicep. Considérez le modèle Bicep suivant, car il définit une output nommée endpoint:

param storageName string
param location string = resourceGroup().location

resource myStorageAccount 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: storageName
  location: location
  kind: 'StorageV2'
  sku:{
    name:'Standard_LRS'
    tier: 'Standard'
  }
  properties: {
    accessTier: 'Hot'
  }
}

output endpoint string = myStorageAccount.properties.primaryEndpoints.blob

Le Bicep définit une sortie nommée endpoint. Pour obtenir la sortie du modèle Bicep, appelez la méthode GetOutput sur une instance IResourceBuilder<AzureBicepResource>, comme illustré dans l’extrait de code C# suivant :

var storage = builder.AddBicepTemplate(
        name: "storage",
        bicepFile: "../infra/storage.bicep"
    );

var endpoint = storage.GetOutput("endpoint");

Dans cet exemple, la sortie du modèle Bicep est récupérée et stockée dans une variable endpoint. En règle générale, vous transmettez cette sortie en tant que variable d’environnement à une autre ressource qui s’appuie dessus. Par exemple, si vous aviez un projet d’API minimal ASP.NET Core qui dépendait de ce point de terminaison, vous pouvez transmettre la sortie en tant que variable d’environnement au projet à l’aide de l’extrait de code suivant :

var storage = builder.AddBicepTemplate(
                name: "storage",
                bicepFile: "../infra/storage.bicep"
            );

var endpoint = storage.GetOutput("endpoint");

var apiService = builder.AddProject<Projects.AspireSample_ApiService>(
        name: "apiservice"
    )
    .WithEnvironment("STORAGE_ENDPOINT", endpoint);

Pour plus d'informations, consultez les résultats de Bicep.

Obtenez des résultats secrets à partir des références de Bicep

Lors de l'utilisation de Bicep, il est essentiel d'éviter les sorties pour les secrets. Si une sortie est considérée comme un secret , ce qui signifie qu’elle ne doit pas être exposée dans des logs ou d’autres endroits, vous pouvez la traiter comme telle. Pour ce faire, stockez le secret dans Azure Key Vault et référencez-le dans le modèle Bicep. L'intégration de .NET Aspireà Azure fournit un modèle permettant de stocker en toute sécurité les sorties du modèle Bicep, en autorisant les ressources à utiliser le paramètre keyVaultName pour stocker les secrets dans Azure Key Vault.

Prenons l’exemple de modèle Bicep suivant pour illustrer ce concept de sécurisation des sorties secrètes :

param databaseAccountName string
param keyVaultName string

param databases array = []

@description('Tags that will be applied to all resources')
param tags object = {}

param location string = resourceGroup().location

var resourceToken = uniqueString(resourceGroup().id)

resource cosmosDb 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
    name: replace('${databaseAccountName}-${resourceToken}', '-', '')
    location: location
    kind: 'GlobalDocumentDB'
    tags: tags
    properties: {
        consistencyPolicy: { defaultConsistencyLevel: 'Session' }
        locations: [
            {
                locationName: location
                failoverPriority: 0
            }
        ]
        databaseAccountOfferType: 'Standard'
    }

    resource db 'sqlDatabases@2023-04-15' = [for name in databases: {
        name: '${name}'
        location: location
        tags: tags
        properties: {
            resource: {
                id: '${name}'
            }
        }
    }]
}

var primaryMasterKey = cosmosDb.listKeys(cosmosDb.apiVersion).primaryMasterKey

resource vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
    name: keyVaultName

    resource secret 'secrets@2023-07-01' = {
        name: 'connectionString'
        properties: {
            value: 'AccountEndpoint=${cosmosDb.properties.documentEndpoint};AccountKey=${primaryMasterKey}'
        }
    }
}

Le modèle Bicep précédent attend un paramètre keyVaultName, entre autres paramètres. Il définit ensuite une ressource Azure Cosmos DB et place un secret dans Azure Key Vault, nommé connectionString qui représente la chaîne de connexion complète à l’instance de Cosmos DB. Pour accéder à cette valeur de chaîne de connexion secrète, vous pouvez utiliser l’extrait de code suivant :

var cosmos = builder.AddBicepTemplate("cosmos", "../infra/cosmosdb.bicep")
    .WithParameter("databaseAccountName", "fallout-db")
    .WithParameter(AzureBicepResource.KnownParameters.KeyVaultName)
    .WithParameter("databases", ["vault-33", "vault-111"]);

var connectionString =
    cosmos.GetSecretOutput("connectionString");

builder.AddProject<Projects.WebHook_Api>("api")
    .WithEnvironment(
        "ConnectionStrings__cosmos",
        connectionString);

Dans l’extrait de code précédent, le modèle cosmos Bicep est ajouté comme référence au builder. La sortie secrète connectionString est récupérée depuis le modèle Bicep et stockée dans une variable. La sortie du secret est ensuite transmise en tant que variable d'environnement (ConnectionStrings__cosmos) au projet api. Cette variable d’environnement est utilisée pour se connecter à l’instance Cosmos DB.

Lorsque cette ressource est déployée, le mécanisme de déploiement sous-jacent va automatiquement référencer des secrets depuis Azure Key Vault. Pour garantir l’isolation des secrets, .NET.NET Aspire crée un coffre de clés par source.

Remarque

Dans mode d’approvisionnement local, le secret est extrait de Key Vault et le définit dans une variable d’environnement. Pour plus d'informations, voir le provisionnement localAzure.

Édition

Lorsque vous publiez votre application, le Azure provisionnement généré par Bicep est utilisé par le Azure Developer CLI pour créer les ressources Azure dans votre abonnement Azure. .NET .NET Aspire génère un manifeste de publication , qui fait également partie intégrante du processus de publication. Le Azure Developer CLI est un outil en ligne de commande qui fournit un ensemble de commandes pour gérer les ressources Azure.

Pour plus d’informations sur la publication et le déploiement, consultez Déployer un projet .NET Aspire pour Azure Container Apps à l’aide du Azure Developer CLI (guide détaillé).