.NET .NET Aspire visión general de la orquestación

.NET .NET Aspire proporciona API para expresar recursos y dependencias dentro de la aplicación distribuida. Además de estas APIs, hay herramientas que habilitan varios escenarios interesantes. El orquestador está diseñado para desarrollo local y no se admite en entornos de producción.

Antes de continuar, considere cierta terminología común que se usa en .NET.NET Aspire:

• modelo de aplicación: colección de recursos que componen la aplicación distribuida (DistributedApplication), definida dentro del espacio de nombres Aspire.Hosting.ApplicationModel. Para obtener una definición más formal, consulte Definir el modelo de aplicación.
• Proyecto de Host/Orquestador de Aplicación: el proyecto .NET que orquesta el modelo de aplicación , denominado con el sufijo *.AppHost (por convención).
• Recurso: un recurso es una parte dependiente de una aplicación, como un proyecto, contenedor, ejecutable, base de datos, caché o servicio en la nube. Representa cualquier parte de la aplicación que se pueda administrar o hacer referencia a ella.
• Integración: una integración es un paquete NuGet para el host de la aplicación que modela un recurso o un paquete que configura un cliente para su uso en una aplicación de consumo. Para obtener más información, consulte .NET.NET Aspire integrations overview.
• Referencia: una referencia define una conexión entre recursos, expresada como una dependencia mediante la API de WithReference. Para obtener más información, vea Recursos de referencia o Referencia de recursos existentes.

Definición del modelo de aplicación

.NET .NET Aspire permite compilar, aprovisionar, implementar, configurar, probar, ejecutar y supervisar las aplicaciones distribuidas de forma eficaz. Estas funcionalidades están basadas en un modelo de aplicación, que define los recursos de .NET.NET Aspire la solución y sus interconexiones.

El modelo de aplicación es más que una lista de recursos, que representa la topología completa de la aplicación. Esto incluye las relaciones entre los recursos, sus dependencias y sus configuraciones. Los recursos pueden incluir proyectos, ejecutables, contenedores, servicios externos y recursos en la nube en los que se basa la aplicación.

En tu .NET.NET Aspire proyecto host de aplicación, tu archivo Program define el modelo de tu aplicación:

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

Cuando llamas a DistributedApplication.CreateBuilder, obtienes una instancia de IDistributedApplicationBuilder, que se usa para configurar el modelo de la aplicación. Este generador proporciona métodos para agregar recursos, definir dependencias y configurar la estructura general de la aplicación. Después de agregar recursos, llame a Build para crear el modelo de aplicación. Las plantillas incluyen código que encadena una llamada a Build(), la cual devuelve una instancia de DistributedApplication, y luego llama a Run().

Proyecto de host de aplicación

El proyecto host de la aplicación controla la ejecución de todos los proyectos que forman parte del proyecto de .NET.NET Aspire. En otras palabras, es responsable de orquestar todas las aplicaciones dentro del modelo de aplicación. El propio proyecto es un .NET proyecto ejecutable que hace referencia al paquete NuGet 📦Aspire.Hosting.AppHost y utiliza el .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>

En el código siguiente se describe un host de aplicación Program con dos referencias de proyecto y una caché de 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();

El código anterior:

• Crea un nuevo generador de modelos de aplicaciones mediante el método CreateBuilder.
• Agrega un recurso de Rediscache denominado "caché" mediante el método AddRedis.
• Agrega un recurso de proyecto denominado "apiservice" mediante el método AddProject.
• Agrega un recurso de proyecto denominado "webfrontend" mediante el método AddProject.
  • Especifica que el proyecto tiene puntos de conexión HTTP externos mediante el método WithExternalHttpEndpoints.
  • Agrega una referencia al recurso de cache y espera a que esté listo mediante los métodos WithReference y WaitFor.
  • Agrega una referencia al recurso de apiservice y espera a que esté listo mediante los métodos WithReference y WaitFor.
• Compila y ejecuta el modelo de aplicación mediante los métodos Build y Run.

El código de ejemplo utiliza la integración de hospedaje .NET AspireRedis.

Para ayudar a visualizar la relación entre el proyecto host de la aplicación y los recursos que describe, tenga en cuenta el diagrama siguiente:

Cada recurso debe tener un nombre único. En este diagrama se muestran cada recurso y las relaciones entre ellos. El recurso de contenedor se denomina "caché" y los recursos del proyecto se denominan "apiservice" y "webfrontend". El proyecto de front-end web hace referencia a los proyectos de caché y servicio de API. Al expresar referencias de esta manera, el proyecto de front-end web dice que depende de estos dos recursos, la "caché" y "apiservice", respectivamente.

Tipos de recursos integrados

Los proyectos .NET.NET Aspire se componen de un conjunto de recursos. Los tipos de recursos base principales en el paquete NuGet 📦Aspire.Hosting.AppHost se describen en la tabla siguiente:

Los recursos del proyecto representan .NET proyectos que forman parte del modelo de aplicación. Al agregar una referencia de proyecto al proyecto host de la aplicación, el SDK de .NET.NET Aspire genera un tipo en el espacio de nombres Projects para cada proyecto al que se hace referencia. Para obtener más información, consulte .NET.NET Aspire SDK: Referencias de proyecto.

Para agregar un proyecto al modelo de aplicación, use el método AddProject:

var builder = DistributedApplication.CreateBuilder(args);

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

Los proyectos se pueden replicar y escalar horizontalmente agregando varias instancias del mismo proyecto al modelo de aplicación. Para configurar réplicas, use el método 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);

El código anterior agrega tres réplicas del recurso de proyecto "apiservice" al modelo de aplicación. Para obtener más información, consulte .NET.NET Aspire panel: Réplicas de recursos.

Recursos de referencia

Una referencia representa una dependencia entre los recursos. Por ejemplo, puede imaginar un escenario en el que un front-end web depende de una Redis memoria caché. Tenga en cuenta el siguiente ejemplo de host de aplicación para código C# Program:

var builder = DistributedApplication.CreateBuilder(args);

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

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

El recurso de proyecto "webfrontend" usa WithReference para agregar una dependencia en el recurso de contenedor "caché". Estas dependencias pueden representar cadenas de conexión o información de detección de servicios. En el ejemplo anterior, se inserta una variable de entorno en el recurso "webfrontend" con el nombre ConnectionStrings__cache. Esta variable de entorno contiene una cadena de conexión que el webfrontend usa para conectarse a Redis a través de la integración .NET AspireRedis, por ejemplo, ConnectionStrings__cache="localhost:62354".

Cadena de conexión y referencias de punto de conexión

Es habitual expresar las dependencias entre los recursos del proyecto. Tenga en cuenta el código de ejemplo siguiente:

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

Las referencias de proyecto a proyecto se controlan de forma diferente a los recursos que tienen cadenas de conexión bien definidas. En lugar de insertar la cadena de conexión en el recurso "webfrontend", se insertan variables de entorno para admitir la detección de servicios.

Al agregar una referencia al proyecto "apiservice", se agregan variables de entorno de detección de servicios al front-end. Esto se debe a que, normalmente, la comunicación entre proyectos se produce a través de HTTP/gRPC. Para obtener más información, consulte .NET.NET Aspire descubrimiento de servicios.

Para obtener puntos de conexión específicos de una ContainerResource o una ExecutableResource, use una de las siguientes API de punto de conexión:

• WithEndpoint
• WithHttpEndpoint
• WithHttpsEndpoint

A continuación, utilice la API de GetEndpoint para obtener el punto de conexión que se puede utilizar para referenciarlo en el método 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);

El parámetro port es el puerto de escucha del contenedor. Para obtener más información sobre los puertos de contenedor, consulte Puertos de contenedor. Para obtener más información sobre la detección de servicios, consulte .NET.NET Aspire service discovery.

Formato de la variable de entorno del punto de servicio

En la sección anterior, el método WithReference se usa para expresar dependencias entre recursos. Cuando los puntos de conexión de servicio generan variables de entorno que se insertan en el recurso dependiente, es posible que el formato no sea obvio. En esta sección se proporcionan detalles sobre este formato.

Cuando un recurso depende de otro recurso, el host de la aplicación inserta variables de entorno en el recurso dependiente. Estas variables de entorno configuran el recurso dependiente para conectarse al recurso del que depende. El formato de las variables de entorno es específico de .NET.NET Aspire y expresa los puntos de conexión de servicio de una manera compatible con Service Discovery.

Los nombres de las variables de entorno del punto de conexión de servicio tienen el prefijo services__ (doble carácter de subrayado), el nombre del servicio, el nombre del punto de conexión y, por último, el índice. El índice admite múltiples extremos para un único servicio, comenzando con 0 para el primer extremo e incrementando para cada extremo adicional.

Tenga en cuenta los siguientes ejemplos de variables de entorno:

services__apiservice__http__0

La variable de entorno anterior expresa el primer punto de conexión HTTP para el servicio apiservice. El valor de la variable de entorno es la dirección URL del punto de conexión de servicio. Un punto de conexión con nombre puede expresarse de la siguiente manera:

services__apiservice__myendpoint__0

En el ejemplo anterior, el servicio apiservice tiene un punto de conexión con nombre denominado myendpoint. El valor de la variable de entorno es la dirección URL del punto de conexión de servicio.

Hacer referencia a los recursos existentes

Algunas situaciones garantizan que haga referencia a un recurso existente, quizás uno que se implemente en un proveedor de nube. Por ejemplo, puede que quiera referirse a una base de datos denominada Azure. En este caso, confiarías en el contexto de ejecución para determinar dinámicamente si el host de la aplicación se está ejecutando en modo "ejecutar" o "publicar". Si se ejecuta localmente y quiere confiar en un recurso en la nube, puede usar la propiedad IsRunMode para agregar condicionalmente la referencia. En su lugar, puede crear el recurso en modo de publicación. Algunas integraciones de hospedaje admiten proporcionar una cadena de conexión que se puede usar directamente para hacer referencia a un recurso existente.

Del mismo modo, puede haber casos de uso en los que quiera integrar .NET.NET Aspire en una solución existente. Un enfoque común consiste en agregar el proyecto host de aplicación .NET.NET Aspire a una solución existente. Dentro de su host de la aplicación, expresa las dependencias agregando referencias de proyecto al host de la aplicación y construyendo el modelo de aplicación. Por ejemplo, un proyecto podría depender de otro. Estas dependencias se expresan mediante el método WithReference. Para obtener más información, consulte Agregar .NET Aspire a una aplicación de .NET existente.

Contexto de ejecución

El IDistributedApplicationBuilder expone un contexto de ejecución (DistributedApplicationExecutionContext), que proporciona información sobre la ejecución actual del host de la aplicación. Este contexto se puede usar para evaluar si el host de la aplicación se está ejecutando en modo "ejecución" o como parte de una operación de publicación. Tenga en cuenta las siguientes propiedades:

• IsRunMode: devuelve true si se está ejecutando la operación actual.
• IsPublishMode: devuelve true si la operación actual es publicar.

Esta información puede ser útil cuando desea ejecutar código condicionalmente en función de la operación actual. Considere el ejemplo siguiente que muestra el uso de la propiedad IsRunMode. En este caso, se usa un método de extensión para generar un nombre de nodo estable para RabbitMQ para las ejecuciones de desarrollo 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;
}

El contexto de ejecución se usa a menudo para agregar recursos o cadenas de conexión condicionalmente que apuntan a recursos existentes. Considere el ejemplo siguiente que muestra cómo agregar condicionalmente Redis o una cadena de conexión en función del contexto de ejecución:

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();

En el código anterior:

• Si el host de la aplicación está en modo "run", se agrega un recurso de contenedor Redis.
• Si el host de la aplicación está en modo "publicar", se agrega una cadena de conexión.

Esta lógica se puede invertir fácilmente para conectarse a un recurso de Redis existente cuando se ejecuta localmente y crear un nuevo recurso de Redis al publicar.

Consulte también

• Orquestación de recursos en .NET.NET Aspire
• Introducción a la visión general de las integraciones .NET.NET Aspire
• .NET .NET Aspire SDK
• Eventos en .NET.NET Aspire
• detección de servicios en .NET.NET Aspire
• .NET .NET Aspire valores predeterminados del servicio
• expresión de parámetros externos
• .NET .NET Aspire introducción a las redes de bucle interno