.NET .NET Aspire 오케스트레이션 개요

.NET .NET Aspire 분산 애플리케이션 내에서 리소스 및 종속성을 표현하기 위한 API를 제공합니다. 이러한 API 외에도, 여러 가지 강력한 시나리오를 가능하게 하는 도구 세트 가 있습니다. 오케스트레이터는 로컬 개발 용도로 사용되며 프로덕션 환경에서는 지원되지 않습니다.

계속하기 전에 .NET.NET Aspire에 사용되는 몇 가지 일반적인 용어를 살펴보세요.

• 앱 모델: DistributedApplication 네임스페이스 내에 정의된 분산 애플리케이션(Aspire.Hosting.ApplicationModel)을 구성하는 리소스 컬렉션입니다. 공식적인 정의를 위해서는 섹션 앱 모델 정의을 참조하십시오.
• 앱 호스트/Orchestrator 프로젝트: 규칙에 따라 .NET 접미사로 명명된 앱 모델을 오케스트레이션하는 프로젝트입니다.
• 리소스: 리소스.NET 프로젝트, 컨테이너, 실행 파일, 데이터베이스, 캐시 또는 클라우드 서비스와 같은 애플리케이션의 종속 부분입니다. 관리하거나 참조할 수 있는 애플리케이션의 모든 부분을 나타냅니다.
• 통합: 통합은 리소스를 모델링하는 앱 호스트를 위한 NuGet 패키지이거나, 소비 앱에서 사용할 클라이언트를 구성하기 위한 패키지입니다. 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요.
• 참조: 참조는 WithReference API를 사용하여 종속성으로 표현된 리소스 간의 연결을 정의합니다. 자세한 내용은 참고 자료 또는 기존 자료를 참조하세요.

메모

.NET .NET Aspire오케스트레이션은 클라우드 네이티브 앱의 구성 및 상호 연결 관리를 간소화하여 로컬 개발 환경을 향상하도록 설계되었습니다. 개발용으로 매우 중요한 도구이지만 Kubernetes같은 프로덕션 환경 시스템을 대체하기 위한 것은 아닙니다. 이 시스템은 해당 컨텍스트에서 뛰어난 능력을 발휘하도록 특별히 설계되었습니다.

앱 모델 정의

.NET .NET Aspire 를 사용하면 분산 애플리케이션을 효율적으로 빌드, 프로비전, 배포, 구성, 테스트, 실행 및 모니터링할 수 있습니다. 이러한 기능은 솔루션의 리소스 .NET.NET Aspire 와 해당 상호 연결을 정의하는 앱 모델을 통해 제공됩니다.

앱 모델은 단순히 리소스 목록 이상이며 애플리케이션의 전체 토폴로지입니다. 여기에는 리소스, 해당 종속성 및 구성 간의 관계가 포함됩니다. 리소스에는 애플리케이션이 사용하는 프로젝트, 실행 파일, 컨테이너, 외부 서비스 및 클라우드 리소스가 포함될 수 있습니다.

.NET .NET Aspire 앱 호스트 프로젝트에서 파일은 Program 앱 모델을 정의합니다.

var builder = DistributedApplication.CreateBuilder(args);

// Add resources to the app model

builder.Build().Run();

호출 DistributedApplication.CreateBuilder할 때 앱 모델을 구성하는 데 사용되는 인스턴스 IDistributedApplicationBuilder를 가져옵니다. 이 작성기에서는 리소스를 추가하고, 종속성을 정의하고, 애플리케이션의 전체 구조를 설정하는 메서드를 제공합니다. 리소스를 추가한 후 호출 Build 하여 앱 모델을 만듭니다. 템플릿에는 먼저 Build()를 호출하여 DistributedApplication 인스턴스를 반환하고, 이후 Run()를 호출하는 코드가 포함됩니다.

앱 호스트 프로젝트

앱 호스트 프로젝트는 .NET.NET Aspire 프로젝트의 일부인 모든 프로젝트를 실행합니다. 즉, 앱 모델 내의 모든 앱을 오케스트레이션해야 합니다. 프로젝트 자체는 .NET 를 참조하고 📦Aspire.Hosting.AppHost NuGet 패키지를 사용하는 실행 가능한 프로젝트이며, .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>

다음 코드에서는 두 개의 프로젝트 참조와 Program 캐시가 있는 앱 호스트 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();

앞의 코드는 다음과 같습니다.

• CreateBuilder 메서드를 사용하여 새 앱 모델 작성기를 만듭니다.
• Redis 메서드를 사용하여 "cache"라는 cacheAddRedis 리소스를 추가합니다.
• AddProject 메서드를 사용하여 "apiservice"라는 프로젝트 리소스를 추가합니다.
• AddProject 메서드를 사용하여 "webfrontend"라는 프로젝트 리소스를 추가합니다.
  • WithExternalHttpEndpoints 메서드를 사용하여 프로젝트에 외부 HTTP 엔드포인트가 있음을 지정합니다.
  • cache 리소스에 대한 참조를 추가하고 WithReference 및 WaitFor 메서드를 사용하여 준비될 때까지 기다립니다.
  • apiservice 리소스에 대한 참조를 추가하고 WithReference 및 WaitFor 메서드를 사용하여 준비될 때까지 기다립니다.
• Build 및 Run 메서드를 사용하여 앱 모델을 빌드하고 실행합니다.

예제 코드는 .NET AspireRedis 호스팅 통합을 사용합니다.

앱 호스트 프로젝트와 앱 호스트 프로젝트가 설명하는 리소스 간의 관계를 시각화하는 데 도움이 되도록 다음 다이어그램을 고려합니다.

각 리소스의 이름은 고유해야 합니다. 이 다이어그램은 각 리소스와 리소스 간의 관계를 보여줍니다. 컨테이너 리소스의 이름은 "cache"이고 프로젝트 리소스의 이름은 "apiservice" 및 "webfrontend"입니다. 웹 프런트 엔드 프로젝트는 캐시 및 API 서비스 프로젝트를 참조합니다. 이러한 방식으로 참조를 표현하는 경우 웹 프런트 엔드 프로젝트는 각각 "캐시" 및 "apiservice"라는 두 리소스에 종속된다고 말합니다.

기본 제공 리소스 종류

.NET .NET Aspire 프로젝트는 리소스 집합으로 구성됩니다. 📦 Aspire에서 주요 기본 리소스 유형은 Hosting.AppHost NuGet 패키지에 포함되어 있으며, 이러한 유형은 다음 표에 설명되어 있습니다.

메서드	리소스 종류	묘사
AddProject	ProjectResource	.NET 프로젝트(예: ASP.NET Core 웹앱).
AddContainer	ContainerResource	Docker 이미지와 같은 컨테이너 이미지입니다.
AddExecutable	ExecutableResource	실행 파일은 Node.js 앱과 같은.
AddParameter	ParameterResource	외부 매개 변수를 표현하는 데 사용할 수 있는 매개 변수 리소스입니다.

프로젝트 리소스는 앱 모델의 일부인 .NET 프로젝트를 나타냅니다. 앱 호스트 프로젝트에 프로젝트 참조를 추가하면 .NET.NET Aspire SDK는 참조된 각 프로젝트에 대한 Projects 네임스페이스에 형식을 생성합니다. 자세한 내용은 .NET.NET Aspire SDK: 프로젝트 참조참조하세요.

앱 모델에 프로젝트를 추가하려면 AddProject 메서드를 사용합니다.

var builder = DistributedApplication.CreateBuilder(args);

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

동일한 프로젝트의 여러 인스턴스를 앱 모델에 추가하여 프로젝트를 복제하고 확장할 수 있습니다. 복제본을 구성하려면 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);

앞의 코드는 "apiservice" 프로젝트 리소스의 복제본 3개를 앱 모델에 추가합니다. 자세한 내용은 .NET.NET Aspire 대시보드: 리소스 복제본참조하세요.

참조 리소스

참조는 리소스 간의 종속성을 나타냅니다. 예를 들어 웹 프런트 엔드가 캐시에 의존하는 시나리오를 Redis 상상할 수 있습니다. 다음 예제 앱 호스트 Program C# 코드를 고려합니다.

var builder = DistributedApplication.CreateBuilder(args);

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

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

"webfrontend" 프로젝트 리소스는 WithReference 사용하여 "캐시" 컨테이너 리소스에 대한 종속성을 추가합니다. 이러한 종속성은 연결 문자열 또는 서비스 검색 정보를 나타낼 수 있습니다. 앞의 예제에서 환경 변수는 "webfrontend" 리소스에 이름이 로 ConnectionStrings__cache 삽입됩니다. 이 환경 변수에는 예를 들어 webfrontend와 같이, Redis가 .NET AspireRedis 통합를 통해 ConnectionStrings__cache="localhost:62354"에 연결하기 위해 사용하는 연결 문자열이 포함됩니다.

연결 문자열 및 엔드포인트 참조

프로젝트 리소스 간의 종속성을 표현하는 것이 일반적입니다. 다음 예제 코드를 고려합니다.

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

프로젝트-프로젝트 참조는 잘 정의된 연결 문자열이 있는 리소스와 다르게 처리됩니다. "webfrontend" 리소스에 연결 문자열을 삽입하는 대신 서비스 검색을 지원하는 환경 변수가 삽입됩니다.

메서드	환경 변수
WithReference(cache)	ConnectionStrings__cache="localhost:62354"
WithReference(apiservice)	services__apiservice__http__0="http://localhost:5455" services__apiservice__https__0="https://localhost:7356"

"apiservice" 프로젝트에 대한 참조를 추가하면 서비스 검색 환경 변수가 프런트 엔드에 추가됩니다. 이는 일반적으로 프로젝트 간 통신이 HTTP/gRPC를 통해 발생하기 때문입니다. 자세한 내용은 .NET.NET Aspire 서비스 검색를 참고하시기 바랍니다.

ContainerResource 또는 ExecutableResource의 특정 엔드포인트를 사용하려면 다음 엔드포인트 API 중 하나를 사용하세요.

• WithEndpoint
• WithHttpEndpoint
• WithHttpsEndpoint

그런 다음 GetEndpoint API를 호출하여 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);

메서드	환경 변수
WithReference(endpoint)	services__myapp__endpoint__0=https://localhost:9043

port 매개 변수는 컨테이너가 수신 대기하는 포트입니다. 컨테이너 포트에 대한 자세한 내용은컨테이너 포트를 참조하세요. 서비스 검색에 대한 자세한 내용은 .NET.NET Aspire 서비스 검색참조하세요.

서비스 엔드포인트 환경 변수 형식

이전 섹션에서는 WithReference 메서드를 사용하여 리소스 간의 종속성을 표현합니다. 서비스 엔드포인트로 인해 환경 변수가 종속 리소스에 삽입되는 경우 형식이 명확하지 않을 수 있습니다. 이 섹션에서는 이 형식에 대한 세부 정보를 제공합니다.

한 리소스가 다른 리소스에 종속되면 앱 호스트는 환경 변수를 종속 리소스에 삽입합니다. 이러한 환경 변수는 종속 리소스가 종속된 리소스에 연결하도록 구성합니다. 환경 변수의 형식은 .NET.NET Aspire에 특정하며, 서비스 엔드포인트를 Service Discovery와 호환되는 방식으로 표현합니다.

서비스 엔드포인트 환경 변수 이름에는 services__(이중 밑줄), 서비스 이름, 엔드포인트 이름 및 마지막으로 인덱스가 접두사로 지정됩니다. 인덱스는 첫 번째 엔드포인트에 대해 0부터 시작하고 각 이후의 엔드포인트마다 증가하여 단일 서비스에 여러 엔드포인트를 지원합니다.

다음 환경 변수 예제를 고려합니다.

services__apiservice__http__0

앞의 환경 변수는 apiservice 서비스에 대한 첫 번째 HTTP 엔드포인트를 나타냅니다. 환경 변수의 값은 서비스 엔드포인트의 URL입니다. 명명된 엔드포인트는 다음과 같이 표현될 수 있습니다.

services__apiservice__myendpoint__0

앞의 예제에서 apiservice 서비스에는 myendpoint이라는 명명된 엔드포인트가 있습니다. 환경 변수의 값은 서비스 엔드포인트의 URL입니다.

기존 리소스 참조

클라우드 공급자에 배포된 기존 리소스를 참조하는 경우도 있습니다. 예를 들어 Azure 데이터베이스를 참조할 수 있습니다. 이 경우 실행 컨텍스트 사용하여 앱 호스트가 "실행" 모드 또는 "게시" 모드에서 실행 중인지 동적으로 결정합니다. 로컬에서 실행 중이고 클라우드 리소스를 사용하려는 경우 IsRunMode 속성을 사용하여 조건부로 참조를 추가할 수 있습니다. 대신 게시 모드에서 리소스를 만들도록 선택할 수 있습니다. 일부 호스팅 통합은 기존 리소스를 참조하는 데 사용할 수 있는 연결 문자열을 직접 제공할 있습니다.

마찬가지로 .NET.NET Aspire 기존 솔루션에 통합하려는 사용 사례가 있을 수 있습니다. 한 가지 일반적인 방법은 .NET.NET Aspire 앱 호스트 프로젝트를 기존 솔루션에 추가하는 것입니다. 앱 호스트에서 프로젝트 참조를 추가하고 앱 모델을 빌드하여 종속성을정의합니다. 예를 들어 한 프로젝트는 다른 프로젝트에 따라 달라질 수 있습니다. 이러한 종속성은 WithReference 메서드를 사용하여 표현됩니다. 자세한 내용은 기존 .NET Aspire 앱에 .NET 추가하기를 참조하세요.

실행 컨텍스트

IDistributedApplicationBuilder 앱 호스트의 현재 실행에 대한 정보를 제공하는 실행 컨텍스트(DistributedApplicationExecutionContext)를 노출합니다. 이 컨텍스트를 사용하여 앱 호스트가 "실행" 모드로 실행되는지 아니면 게시 작업의 일부로 실행되는지 여부를 평가할 수 있습니다. 다음 속성을 고려합니다.

• IsRunMode: 현재 작업이 실행 중인 경우 true 반환합니다.
• IsPublishMode: 현재 작업이 게시 중인 경우 true을 반환합니다.

이 정보는 현재 작업에 따라 코드를 조건부로 실행하려는 경우에 유용할 수 있습니다. IsRunMode 속성을 사용하는 방법을 보여 주는 다음 예제를 고려해 보세요. 이 경우 확장 메서드는 로컬 개발 실행에 대한 RabbitMQ 안정적인 노드 이름을 생성하는 데 사용됩니다.

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

실행 컨텍스트는 종종 기존 리소스를 가리키는 리소스 또는 연결 문자열을 조건부로 추가하는 데 사용됩니다. 실행 컨텍스트에 따라 조건부로 Redis 또는 연결 문자열을 추가하는 방법을 보여 주는 다음 예제를 살펴보겠습니다.

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

앞의 코드에서 다음을 수행합니다.

• 앱 호스트가 "실행" 모드인 경우 컨테이너 리소스가 Redis 추가됩니다.
• 앱 호스트가 "게시" 모드인 경우 연결 문자열이 추가됩니다.

이 논리를 쉽게 반전하여 로컬로 실행할 때 기존 Redis 리소스에 연결하고 게시할 때 새 Redis 리소스를 만들 수 있습니다.

중요하다

.NET .NET Aspire 리소스 작성기의 형식을 제어하는 일반적인 API를 제공하여 리소스가 실행 모드에 따라 다르게 동작할 수 있도록 합니다. 플루언트 API에는 RunAs* 및 PublishAs*접두사가 붙어 있습니다. RunAs* API는 로컬 개발(또는 실행 모드) 동작에 영향을 주지만 PublishAs* API는 리소스 게시에 영향을 줍니다. Azure 리소스에서 이러한 API를 사용하는 방법에 대한 자세한 내용은 Azure기존 리소스 사용을 참조하세요.

참고로

• 에서 리소스 오케스트레이션 .NET.NET Aspire
• .NET .NET Aspire 통합 개요
• .NET .NET Aspire SDK (소프트웨어 개발 키트)
• 이벤트 .NET.NET Aspire
• .NET .NET Aspire 서비스 검색
• .NET .NET Aspire 서비스의 기본값은
• 외부 매개 변수의 표현
• .NET .NET Aspire 내부 루프 네트워킹 개요