Vue d’ensemble de l’orchestration .NET.NET Aspire

2025-04-24

.NET .NET Aspire fournit des API pour exprimer des ressources et des dépendances au sein de votre application distribuée. En plus de ces API, il existe des outils qui permettent plusieurs scénarios attrayants. L’orchestrateur est destiné à des fins de développement local et n’est pas pris en charge dans les environnements de production.

Avant de continuer, tenez compte de certaines terminologies courantes utilisées dans .NET.NET Aspire:

Modèle d’application : collection de ressources qui composent votre application distribuée (DistributedApplication), définie dans l’espace Aspire.Hosting.ApplicationModel de noms. Pour obtenir une définition plus formelle, consultez Définir le modèle d’application.
Projet hôte/Orchestrateur d’application : .NET projet qui orchestre le modèle d’application, nommé avec le *. Suffixe AppHost (par convention).
Ressource : une ressource est une partie dépendante d’une application, telle qu’un projet, un conteneur, un exécutable, une .NET base de données, un cache ou un service cloud. Il représente toute partie de l’application qui peut être gérée ou référencée.
<h;c0>Intégration</c0>: Une intégration est un package NuGet pour l’<h;c1>hôte de l'application</c1> qui modélise une <h;c2>ressource</c2> ou un package qui configure un client pour une application d'utilisation. Pour plus d’informations, consultez .NET.NET Aspire la vue d’ensemble des intégrations.
Référence : une référence définit une connexion entre les ressources, exprimée en tant que dépendance à l’aide de l’API WithReference . Pour plus d’informations, consultez Ressources de référence ou Ressources existantes de référence.

Remarque

.NET .NET AspireL’orchestration est conçue pour améliorer votre expérience de développement local en simplifiant la gestion de la configuration et des interconnexions de votre application native cloud. Bien qu’il s’agit d’un outil précieux pour le développement, il n’est pas destiné à remplacer les systèmes d’environnement de production comme Kubernetes, qui sont spécifiquement conçus pour exceller dans ce contexte.

Définir le modèle d’application

.NET .NET Aspire vous permet de générer, provisionner, déployer, configurer, tester, exécuter et surveiller efficacement vos applications distribuées. Ces fonctionnalités sont alimentées par un modèle d’application, qui définit les ressources de votre .NET.NET Aspire solution et leurs interconnexions.

Le modèle d’application est plus qu’une liste de ressources , il représente la topologie complète de votre application. Cela inclut les relations entre les ressources, leurs dépendances et leurs configurations. Les ressources peuvent inclure des projets, des exécutables, des conteneurs, des services externes et des ressources cloud sur lesquelles votre application s’appuie.

Dans votre .NET.NET Aspire projet hôte d’application, votre Program fichier définit votre modèle d’application :

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

Lorsque vous appelez DistributedApplication.CreateBuilder, vous obtenez une instance de IDistributedApplicationBuilder, qui est utilisée pour configurer votre modèle d’application. Ce générateur fournit des méthodes pour ajouter des ressources, définir des dépendances et configurer la structure globale de votre application. Une fois que vous avez ajouté des ressources, appelez Build pour créer le modèle d’application. Les modèles incluent du code qui chaîne un appel à Build():qui retourne une DistributedApplication instance, puis appelle Run().

Projet hôte d’application

Le projet hôte d’application gère l’exécution de tous les projets qui font partie du projet .NET.NET Aspire. En d’autres termes, il est responsable de l’orchestration de toutes les applications au sein du modèle d’application. Le projet lui-même est un .NET projet exécutable qui fait référence au package NuGet 📦Aspire.Hosting.AppHost, et utilise le kit de développement logiciel .NET.NET Aspire (SDK) :

<Project Sdk="Microsoft.NET.Sdk">

    <Sdk Name="Aspire.AppHost.Sdk" Version="9.1.0" />
    
    <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net9.0</TargetFramework>
        <!-- Omitted for brevity -->
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Aspire.Hosting.AppHost" Version="9.1.0" />
    </ItemGroup>

    <!-- Omitted for brevity -->

</Project>

Le code suivant décrit un hôte d’application Program avec deux références de projet et un cache Redis :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithExternalHttpEndpoints()
       .WithReference(cache)
       .WaitFor(cache)
       .WithReference(apiService)
       .WaitFor(apiService);

builder.Build().Run();

Code précédent :

Crée un générateur de modèles d’application à l’aide de la méthode CreateBuilder.
Ajoute une ressource Rediscache nommée « cache » à l’aide de la méthode AddRedis.
Ajoute une ressource de projet nommée « apiservice » à l’aide de la méthode AddProject.
Ajoute une ressource de projet nommée « webfrontend » à l’aide de la méthode AddProject.
- Spécifie que le projet a des points de terminaison HTTP externes à l’aide de la méthode WithExternalHttpEndpoints.
- Ajoute une référence à la ressource cache et attend qu’elle soit prête à utiliser les méthodes WithReference et WaitFor.
- Ajoute une référence à la ressource apiservice et attend qu’elle soit prête à utiliser les méthodes WithReference et WaitFor.
Génère et exécute le modèle d’application à l’aide des méthodes Build et Run.

L’exemple de code utilise l’intégration d’hébergement.NET AspireRedis.

Pour vous aider à visualiser la relation entre le projet hôte d’application et les ressources qu’il décrit, tenez compte du diagramme suivant :

Chaque ressource doit être nommée de manière unique. Ce diagramme montre chaque ressource et les relations entre elles. La ressource de conteneur est nommée « cache » et les ressources du projet sont nommées « apiservice » et « webfrontend ». Le projet web d'interface fait référence aux projets de cache et d'API. Lorsque vous exprimez des références de cette façon, le projet front-end web dit qu’il dépend de ces deux ressources, le « cache » et « apiservice » respectivement.

Types de ressources intégrés

Les projets .NET.NET Aspire sont constitués d'un ensemble de ressources. Les principaux types de ressources de base du package NuGet 📦Aspire.Hosting.AppHost sont décrits dans le tableau suivant :

Méthode	Type de ressource	Descriptif
AddProject	ProjectResource	Un projet .NET, par exemple, une application web ASP.NET Core.
AddContainer	ContainerResource	Image conteneur, telle qu’une image Docker.
AddExecutable	ExecutableResource	Fichier exécutable, tel qu’une Node.js application.
AddParameter	ParameterResource	Ressource de paramètre qui peut être utilisée pour exprimer des paramètres externes.

Les ressources de projet représentent .NET projets qui font partie du modèle d’application. Lorsque vous ajoutez une référence de projet au projet hôte d’application, le sdk .NET.NET Aspire génère un type dans l’espace de noms Projects pour chaque projet référencé. Pour plus d’informations, consultez .NET.NET Aspire sdk : Références de projet.

Pour ajouter un projet au modèle d’application, utilisez la méthode AddProject :

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

Les projets peuvent être répliqués et mis à l’échelle en ajoutant plusieurs instances du même projet au modèle d’application. Pour configurer des réplicas, utilisez la méthode WithReplicas :

var builder = DistributedApplication.CreateBuilder(args);

// Adds the project "apiservice" of type "Projects.AspireApp_ApiService".
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReplicas(3);

Le code précédent ajoute trois réplicas de la ressource de projet « apiservice » au modèle d’application. Pour plus d’informations, consultez tableau .NET.NET Aspire de bord : Réplicas de ressources.

Ressources de référence

Une référence représente une dépendance entre les ressources. Par exemple, vous pouvez probablement imaginer un scénario où un front-end web dépend d’un Redis cache. Considérez l’exemple d’hôte d’application suivant Program code C# :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache);

La ressource de projet « webfrontend » utilise WithReference pour ajouter une dépendance à la ressource de conteneur « cache ». Ces dépendances peuvent représenter des chaînes de connexion ou des informations de découverte de service . Dans l’exemple précédent, une variable d’environnement est injectée dans la ressource « webfrontend » avec le nom ConnectionStrings__cache. Cette variable d’environnement contient une chaîne de connexion que webfrontend utilise pour se connecter à Redis via l’intégration .NET AspireRedis, par exemple, ConnectionStrings__cache="localhost:62354".

Références de chaîne de connexion et de point de terminaison

Il est courant d’exprimer des dépendances entre les ressources du projet. Considérez l’exemple de code suivant :

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice");

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
       .WithReference(cache)
       .WithReference(apiservice);

Les références de projet à projet sont gérées différemment des ressources qui ont des chaînes de connexion bien définies. Au lieu d’injecter une chaîne de connexion dans la ressource « webfrontend », les variables d’environnement pour prendre en charge la découverte de service sont injectées.

Méthode	Variable d’environnement
`WithReference(cache)`	`ConnectionStrings__cache="localhost:62354"`
`WithReference(apiservice)`	`services__apiservice__http__0="http://localhost:5455"` `services__apiservice__https__0="https://localhost:7356"`

L’ajout d’une référence au projet « apiservice » entraîne l’ajout de variables d’environnement de découverte de service au serveur frontal. En règle générale, la communication projet-à-projet se produit sur HTTP/gRPC. Pour plus d’informations, consultez .NET.NET Aspire la découverte des services.

Pour obtenir des points de terminaison spécifiques à partir d’un ContainerResource ou d’un ExecutableResource, utilisez l’une des API de point de terminaison suivantes :

Appelez ensuite l’API GetEndpoint pour obtenir le point de terminaison qui peut être utilisé pour référencer le point de terminaison dans la méthode WithReference :

var builder = DistributedApplication.CreateBuilder(args);

var customContainer = builder.AddContainer("myapp", "mycustomcontainer")
                             .WithHttpEndpoint(port: 9043, name: "endpoint");

var endpoint = customContainer.GetEndpoint("endpoint");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
                        .WithReference(endpoint);

Méthode	Variable d’environnement
`WithReference(endpoint)`	`services__myapp__endpoint__0=https://localhost:9043`

Le paramètre port est le port sur lequel le conteneur écoute. Pour plus d’informations sur les ports de conteneur, consultez Ports de conteneur. Pour plus d’informations sur la découverte de services, consultez .NET.NET Aspire.

Format de variable d’environnement de point de terminaison de service

Dans la section précédente, la méthode WithReference est utilisée pour exprimer des dépendances entre les ressources. Lorsque les points de terminaison de service entraînent l’injection de variables d’environnement dans la ressource dépendante, le format peut ne pas être évident. Cette section fournit des détails sur ce format.

Quand une ressource dépend d’une autre ressource, l’hôte de l’application injecte des variables d’environnement dans la ressource dépendante. Ces variables d’environnement configurent la ressource dépendante pour qu’elle se connecte à la ressource dont elle dépend. Le format des variables d’environnement est spécifique aux .NET.NET Aspire points de terminaison de service et exprime les points de terminaison de service d’une manière compatible avec la découverte de services.

Les noms des variables d’environnement de point de terminaison de service sont précédés de services__ (trait de soulignement double), puis du nom du service, du nom du point de terminaison et enfin de l’index. L’index prend en charge plusieurs points de terminaison pour un seul service, en commençant par 0 pour le premier point de terminaison et l’incrémentation pour chaque point de terminaison.

Tenez compte des exemples de variables d’environnement suivants :

services__apiservice__http__0

La variable d’environnement précédente exprime le premier point de terminaison HTTP pour le service apiservice. La valeur de la variable d’environnement est l’URL du point de terminaison de service. Un point de terminaison nommé peut être exprimé comme suit :

services__apiservice__myendpoint__0

Dans l’exemple précédent, le service apiservice a un point de terminaison nommé appelé myendpoint. La valeur de la variable d’environnement est l’URL du point de terminaison de service.

Référencer les ressources existantes

Certaines situations vous justifient de référencer une ressource existante, peut-être une ressource déployée sur un fournisseur de cloud. Par exemple, vous pouvez référencer une base de données Azure. Dans ce cas, vous devez vous appuyer sur le contexte d’exécution pour déterminer dynamiquement si l’hôte de l’application s’exécute en mode « Exécuter » ou en mode « publier ». Si vous exécutez localement et que vous souhaitez vous appuyer sur une ressource cloud, vous pouvez utiliser la propriété IsRunMode pour ajouter conditionnellement la référence. Vous pouvez choisir de créer plutôt la ressource en mode publication. Certaines intégrations d’hébergement prennent en charge la fourniture d’une chaîne de connexion directement, qui peut être utilisée pour référencer une ressource existante.

De même, il peut y avoir des cas d’usage où vous souhaitez intégrer .NET.NET Aspire dans une solution existante. Une approche courante consiste à ajouter le projet hôte d’application .NET.NET Aspire à une solution existante. Au sein de votre hôte d’application, vous exprimez des dépendances en ajoutant des références de projet à l’hôte de l’application et en créant le modèle d’application. Par exemple, un projet peut dépendre d’un autre projet. Ces dépendances sont exprimées à l’aide de la méthode WithReference. Pour plus d’informations, consultez Ajouter .NET Aspire à une application existante.NET.

Contexte d’exécution

Le IDistributedApplicationBuilder expose un contexte d’exécution (DistributedApplicationExecutionContext), qui fournit des informations sur l’exécution actuelle de l’hôte d’application. Ce contexte peut être utilisé pour déterminer si l’hôte de l’application s’exécute en mode « exécuter » ou dans le cadre d’une opération de publication. Tenez compte des propriétés suivantes :

IsRunMode: retourne true si l’opération actuelle est en cours d’exécution.
IsPublishMode: retourne true si l’opération en cours est une publication.

Ces informations peuvent être utiles lorsque vous souhaitez exécuter du code de manière conditionnelle en fonction de l’opération actuelle. Prenons l’exemple suivant qui illustre l’utilisation de la propriété IsRunMode. Dans ce cas, une méthode d’extension est utilisée pour générer un nom de nœud stable pour RabbitMQ pour les exécutions de développement local.

private static IResourceBuilder<RabbitMQServerResource> RunWithStableNodeName(
    this IResourceBuilder<RabbitMQServerResource> builder)
{
    if (builder.ApplicationBuilder.ExecutionContext.IsRunMode)
    {
        builder.WithEnvironment(context =>
        {
            // Set a stable node name so queue storage is consistent between sessions
            var nodeName = $"{builder.Resource.Name}@localhost";
            context.EnvironmentVariables["RABBITMQ_NODENAME"] = nodeName;
        });
    }

    return builder;
}

Le contexte d’exécution est souvent utilisé pour ajouter conditionnellement des ressources ou des chaînes de connexion qui pointent vers des ressources existantes. Prenons l’exemple suivant qui illustre l’ajout conditionnel de Redis ou d’une chaîne de connexion en fonction du contexte d’exécution :

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.ExecutionContext.IsRunMode
    ? builder.AddRedis("redis")
    : builder.AddConnectionString("redis");

builder.AddProject<Projects.WebApplication>("api")
       .WithReference(redis);

builder.Build().Run();

Dans le code précédent :

Si l’hôte de l’application est en mode « exécuter », une Redis ressource de conteneur est ajoutée.
Si l’hôte de l’application est en mode « publier », une chaîne de connexion est ajoutée.

Cette logique peut facilement être inversée pour se connecter à une ressource Redis existante lorsque vous exécutez localement et créer une ressource Redis lors de la publication.

Important

.NET .NET Aspire fournit des API courantes pour contrôler la modalité des générateurs de ressources, ce qui permet aux ressources de se comporter différemment en fonction du mode d’exécution. Les API Fluent sont précédées de RunAs* et de PublishAs*. Les API RunAs* influencent le comportement de développement local (ou mode d’exécution), tandis que les API PublishAs* influencent la publication de la ressource. Pour plus d’informations sur la façon dont les Azure ressources utilisent ces API, consultez Utiliser des ressources existantesAzure.