Compartilhar via

visão geral da orquestração .NET.NET Aspire

.NET .NET Aspire fornece APIs para expressar recursos e dependências em seu aplicativo distribuído. Além dessas APIs, há ferramentas que permitem vários cenários atraentes. O orquestrador destina-se à finalidade de desenvolvimento local e não tem suporte em ambientes de produção.

Antes de continuar, considere alguma terminologia comum usada em .NET.NET Aspire:

  • modelo de aplicativo: uma coleção de recursos que compõem seu aplicativo distribuído (DistributedApplication), definido no namespace Aspire.Hosting.ApplicationModel. Para obter uma definição mais formal, consulte Definir o modelo de aplicativo.
  • Projeto Host de Aplicativo/Orquestrador: o projeto .NET que orquestra o modelo de aplicativo, nomeado com o sufixo *.AppHost (por convenção).
  • Recurso: um recurso é uma parte dependente de um aplicativo, como um projeto, contêiner, executável, banco de dados, cache ou serviço de nuvem. Ele representa qualquer parte do aplicativo que possa ser gerenciada ou referenciada.
  • Integração: uma integração é um pacote NuGet para o host do aplicativo que modela um recurso ou um pacote que configura um cliente para uso em um aplicativo consumidor. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.
  • Referência: uma referência define uma conexão entre recursos, expressa como uma dependência usando a API WithReference. Para obter mais informações, consulte recursos de referência ou consulte recursos existentes.

Nota

A orquestração do .NET.NET Aspire foi projetada para aprimorar sua experiência de desenvolvimento local, simplificando o gerenciamento da configuração e das interconexões do aplicativo nativo da nuvem. Embora seja uma ferramenta inestimável para o desenvolvimento, não se destina a substituir sistemas de ambiente de produção como Kubernetes, que são especificamente projetados para se destacar nesse contexto.

Definir o modelo de aplicativo

.NET .NET Aspire permite que você crie, provisione, implante, configure, teste, execute e monitore seus aplicativos distribuídos com eficiência. Esses recursos são alimentados por um modelo de aplicativo, que define os recursos em sua .NET.NET Aspire solução e suas interconexões.

O modelo de aplicativo é mais do que apenas uma lista de recursos, que representa a topologia completa do seu aplicativo. Isso inclui as relações entre recursos, suas dependências e suas configurações. Os recursos podem incluir projetos, executáveis, contêineres, serviços externos e recursos de nuvem dos quais seu aplicativo depende.

.NET .NET Aspire No projeto do host do aplicativo, o Program arquivo define o modelo de aplicativo:

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

Quando você chama DistributedApplication.CreateBuilder, você obtém uma instância de IDistributedApplicationBuilder, que é usada para configurar o modelo do seu aplicativo. Esse construtor fornece métodos para adicionar recursos, definir dependências e configurar a estrutura geral do aplicativo. Depois de adicionar recursos, chame Build para criar o modelo de aplicativo. Os modelos contêm código que encadeia uma chamada para Build(), que retorna uma instância de DistributedApplication, e, em seguida, chama Run().

Projeto de host do aplicativo

O projeto de host do aplicativo manipula a execução de todos os projetos que fazem parte do projeto .NET.NET Aspire. Em outras palavras, ele é responsável por orquestrar todos os aplicativos dentro do modelo de aplicativo. O projeto em si é um .NET projeto executável que faz referência ao 📦Aspire. Pacote NuGet Hosting.AppHost e usa o .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>

O código a seguir descreve um host de aplicativo Program com duas referências de projeto e um cache 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();

O código anterior:

  • Cria um novo construtor de modelos de aplicativo usando o método CreateBuilder.
  • Adiciona um recurso Rediscache chamado "cache" usando o método AddRedis.
  • Adiciona um recurso de projeto chamado "apiservice" usando o método AddProject.
  • Adiciona um recurso de projeto chamado "webfrontend" usando o método AddProject.
    • Especifica que o projeto possui endpoints HTTP externos, pelo método WithExternalHttpEndpoints.
    • Adiciona uma referência ao recurso cache e aguarda que ele esteja pronto usando os métodos WithReference e WaitFor.
    • Adiciona uma referência ao recurso apiservice e aguarda que ele esteja pronto usando os métodos WithReference e WaitFor.
  • Cria e executa o modelo de aplicativo usando os métodos Build e Run.

O código de exemplo usa a integração de hospedagem .NET AspireRedis.

Para ajudar a visualizar a relação entre o projeto de host do aplicativo e os recursos descritos, considere o seguinte diagrama:

a relação entre os projetos no modelo de aplicativo inicial do .NET.NET Aspire.

Cada recurso deve ser nomeado exclusivamente. Este diagrama mostra cada recurso e as relações entre eles. O recurso de contêiner é chamado de "cache" e os recursos do projeto são chamados de "apiservice" e "webfrontend". O projeto de front-end da Web faz referência aos projetos de cache e serviço de API. Quando você está expressando referências dessa forma, o projeto de front-end da Web está dizendo que ele depende desses dois recursos, o "cache" e o "apiservice", respectivamente.

Tipos de recursos integrados

.NET .NET Aspire projetos são compostos por um conjunto de recursos. Os principais tipos de recursos base no pacote NuGet 📦Aspire.Hosting.AppHost são descritos na tabela a seguir:

Método Tipo de recurso Descrição
AddProject ProjectResource Um projeto .NET, por exemplo, um aplicativo Web ASP.NET Core.
AddContainer ContainerResource Uma imagem de contêiner, como uma imagem Docker.
AddExecutable ExecutableResource Um arquivo executável, como um aplicativo Node.js.
AddParameter ParameterResource Um recurso de parâmetro que pode ser usado para expressar parâmetros externos.

Os recursos de projetos representam .NET projetos que fazem parte do modelo de aplicativo. Quando você adiciona uma referência de projeto ao projeto de host do aplicativo, o SDK do .NET.NET Aspire gera um tipo no namespace Projects para cada projeto referenciado. Para obter mais informações, consulte .NET.NET Aspire SDK: referências de projeto.

Para adicionar um projeto ao modelo de aplicativo, use o 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");

Os projetos podem ser replicados e dimensionados adicionando várias instâncias do mesmo projeto ao modelo de aplicativo. Para configurar réplicas, use o 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);

O código anterior adiciona três réplicas do recurso de projeto "apiservice" ao modelo de aplicativo. Para obter mais informações, consulte o painel de controle: ".NET.NET AspireRéplicas de Recurso".

Recursos de referência

Uma referência representa uma dependência entre recursos. Por exemplo, você provavelmente pode imaginar um cenário em que um front-end da Web depende de um Redis cache. Considere o seguinte exemplo de host de aplicativo Program código C#:

var builder = DistributedApplication.CreateBuilder(args);

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

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

O recurso de projeto "webfrontend" usa WithReference para adicionar uma dependência ao recurso de contêiner "cache". Essas dependências podem representar cadeias de conexão ou informações de descoberta de serviço. No exemplo anterior, uma variável de ambiente é injetada no recurso "webfrontend" com o nome ConnectionStrings__cache. Essa variável de ambiente contém uma string de conexão que o webfrontend usa para se conectar a Redis por meio da integração .NET AspireRedis, por exemplo, ConnectionStrings__cache="localhost:62354".

Referências da cadeia de conexão e do ponto de extremidade

É comum expressar dependências entre os recursos do projeto. Considere o seguinte código de exemplo:

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

As referências projeto a projeto são tratadas de forma diferente dos recursos que têm cadeias de conexão bem definidas. Em vez de a cadeia de conexão ser injetada no recurso "webfrontend", são injetadas variáveis de ambiente para dar suporte à descoberta de serviço.

Método Variável de ambiente
WithReference(cache) ConnectionStrings__cache="localhost:62354"
WithReference(apiservice) services__apiservice__http__0="http://localhost:5455"
services__apiservice__https__0="https://localhost:7356"

Adicionar uma referência ao projeto "apiservice" resulta em variáveis de ambiente de descoberta de serviço sendo adicionadas ao front-end. Isso ocorre porque, normalmente, a comunicação projeto a projeto ocorre por HTTP/gRPC. Para obter mais informações, consulte .NET.NET Aspire descoberta de serviço.

Para obter pontos de extremidade específicos de um ContainerResource ou um ExecutableResource, use uma das seguintes APIs de ponto de extremidade:

Em seguida, chame a API GetEndpoint para obter o ponto de extremidade que pode ser usado para referenciar o ponto de extremidade no 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);
Método Variável de ambiente
WithReference(endpoint) services__myapp__endpoint__0=https://localhost:9043

O parâmetro port é a porta onde o contêiner está escutando. Para obter mais informações sobre portas de contêiner, consulte portas de contêiner. Para obter mais informações sobre descoberta de serviço, consulte .NET.NET Aspire descoberta de serviço.

Formato da variável de ambiente do ponto de extremidade do serviço

Na seção anterior, o método WithReference é usado para expressar dependências entre recursos. Quando pontos de extremidade de serviço resultam em variáveis de ambiente sendo injetadas no recurso dependente, o formato pode não ser óbvio. Esta seção fornece detalhes sobre esse formato.

Quando um recurso depende de outro recurso, o host do aplicativo injeta variáveis de ambiente no recurso dependente. Essas variáveis de ambiente configuram o recurso dependente para se conectar ao recurso do qual ele depende. O formato das variáveis de ambiente é específico para .NET.NET Aspire e expressa endpoints de serviço compatíveis com Descoberta de Serviço.

Os nomes das variáveis de ambiente do ponto de extremidade de serviço são prefixados com services__ (sublinhado duplo), o nome do serviço, o nome do ponto de extremidade e, por fim, o índice. O índice suporta múltiplos endpoints para um único serviço, começando com 0 para o primeiro endpoint e incrementando para cada endpoint.

Considere os seguintes exemplos de variável de ambiente:

services__apiservice__http__0

A variável de ambiente anterior expressa o primeiro ponto de extremidade HTTP para o serviço apiservice. O valor da variável de ambiente é a URL do endpoint do serviço. Um ponto de extremidade nomeado pode ser expresso da seguinte maneira:

services__apiservice__myendpoint__0

No exemplo anterior, o serviço apiservice tem um ponto de extremidade nomeado chamado myendpoint. O valor da variável de ambiente é a URL do endpoint do serviço.

Referenciar recursos existentes

Algumas situações garantem que você faça referência a um recurso existente, talvez um que seja implantado em um provedor de nuvem. Por exemplo, talvez você queira fazer referência a um banco de dados Azure. Nesse caso, você contaria com o contexto de execução para determinar dinamicamente se o host do aplicativo está em execução no modo "executar" ou "publicar". Se você estiver executando localmente e quiser contar com um recurso de nuvem, poderá usar a propriedade IsRunMode para adicionar condicionalmente a referência. Em vez disso, você pode optar por criar o recurso no modo de publicação. Algumas integrações de hospedagem suportam fornecer uma cadeia de conexão diretamente, que pode ser usada para fazer referência a um recurso existente.

Da mesma forma, pode haver casos de uso em que você deseja integrar .NET.NET Aspire em uma solução existente. Uma abordagem comum é adicionar o projeto host do aplicativo .NET.NET Aspire a uma solução existente. No host do aplicativo, você expressa dependências adicionando referências de projeto ao host do aplicativo e criando o modelo de aplicativo. Por exemplo, um projeto pode depender de outro. Essas dependências são expressas usando o método WithReference. Para obter mais informações, consulte Adicionar .NET Aspire a um aplicativo .NET existente.

Contexto de execução

O IDistributedApplicationBuilder expõe um contexto de execução (DistributedApplicationExecutionContext), que fornece informações sobre a execução atual do host do aplicativo. Esse contexto pode ser usado para avaliar se o host do aplicativo está ou não executando como modo de "execução" ou como parte de uma operação de publicação. Considere as seguintes propriedades:

  • IsRunMode: retorna true se a operação atual estiver em execução.
  • IsPublishMode: retorna true se a operação atual for de publicação.

Essas informações podem ser úteis quando você deseja executar condicionalmente o código com base na operação atual. Considere o exemplo a seguir que demonstra o uso da propriedade IsRunMode. Nesse caso, utiliza-se um método de extensão para gerar um nome de nó estável para RabbitMQ em execuções locais de desenvolvimento.

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

O contexto de execução geralmente é usado para adicionar condicionalmente recursos ou cadeias de conexão que apontam para recursos existentes. Considere o exemplo a seguir que demonstra a adição condicional de Redis ou uma cadeia de conexão com base no contexto de execução:

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

No código anterior apresentado:

  • Se o host do aplicativo estiver no modo "executar", um Redis recurso de contêiner será adicionado.
  • Se o host do aplicativo estiver no modo "publicar", uma cadeia de conexão será adicionada.

Essa lógica pode ser facilmente invertida para se conectar a um recurso de Redis existente quando você estiver executando localmente e criar um novo recurso Redis quando estiver publicando.

Importante

.NET .NET Aspire fornece APIs comuns para controlar a modalidade dos construtores de recursos, permitindo que os recursos se comportem de forma diferente com base no modo de execução. As APIs fluentes são prefixadas com RunAs* e PublishAs*. As APIs de RunAs* influenciam o comportamento do desenvolvimento local (ou modo de execução), enquanto as APIs de PublishAs* influenciam a publicação do recurso. Para obter mais informações sobre como os recursos de Azure usam essas APIs, consulte Usar recursos de Azure existentes.

Consulte também