.NET .NET Aspire에서 리소스를 오케스트레이션합니다.

2025-04-30

이 문서에서는 앱 호스트 프로젝트에서 코드를 작성하여 리소스의 동작을 추가로 사용자 지정하는 방법을 알아봅니다. 리소스는 .NET.NET Aspire 클라우드 네이티브 애플리케이션의 종속 부분입니다. 리소스 종류는 다음과 같습니다.

.NET 프로젝트: 클라우드 네이티브 애플리케이션의 특정 기능을 담당하며 별도의 개발자 팀이 빌드하는 사용자 지정 마이크로 서비스입니다.
실행 가능한: Node.js 및 Orleans 도구와 같은 툴을 사용하여 마이크로 서비스를 빌드해야 하는 경우, 이는 실행 가능한 리소스로 작동합니다.
컨테이너: 솔루션에 특정 이미지를 기반으로 컨테이너를 추가할 Docker 수 있습니다 .NET Aspire .
통합 리소스: 통합은 종종 애플리케이션에 데이터베이스, 캐시 및 메시징 서비스와 같은 리소스를 추가합니다.

오케스트레이션의 .NET.NET Aspire 기본 사항 및 리소스를 관리하는 방법은 오케스트레이션 개요를 참조.NET.NET Aspire하세요.

리소스 명명 규칙

리소스의 이름은 .NET Aspire에서 설정한 명명 제한 및 그것이 나타내는 기술을 따라야 합니다. 예를 들어 리소스의 .NET Aspire 최대 이름 길이는 64자이지만 Azure 컨테이너 앱의 최대 길이는 32자입니다. 컨테이너 리소스를 .NET AspireAzure게시할 때 이름은 길이가 32자를 초과하지 않아야 합니다.

.NET .NET Aspire 리소스 이름은 다음 기본 규칙을 따라야 합니다.

길이는 1자에서 64자 사이여야 합니다.
ASCII 문자로 시작해야 합니다.
ASCII 문자, 숫자 및 하이픈만 포함해야 합니다.
하이픈으로 끝나지 않아야 합니다.
연속 하이픈을 포함해서는 안 됩니다.

명시적 리소스 시작 구성

프로젝트, 실행 파일 및 컨테이너 리소스는 기본적으로 분산 애플리케이션에서 자동으로 시작됩니다. WithExplicitStart 메서드를 사용하여 명시적 시작 명령을 기다리도록 리소스를 구성할 수 있습니다. WithExplicitStart 구성된 리소스는 KnownResourceStates.NotStarted사용하여 초기화됩니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

builder.AddProject<Projects.AspireApp_DbMigration>("dbmigration")
       .WithReference(postgresdb)
       .WithExplicitStart();

이전 코드 "dbmigration" 에서 리소스는 분산 애플리케이션으로 자동으로 시작되지 않도록 구성됩니다.

명시적 시작이 있는 리소스는 "시작" 명령을 클릭하여 .NET.NET Aspire 대시보드에서 시작할 수 있습니다. 자세한 내용은 대시보드: 리소스 중지 또는 시작을 참조.NET.NET Aspire하세요.

리소스 대기 중

경우에 따라 다른 리소스를 시작하기 전에 리소스가 준비될 때까지 기다리는 것이 좋습니다. 예를 들어 데이터베이스에 의존하는 API를 시작하기 전에 데이터베이스가 준비될 때까지 기다리는 것이 좋습니다. 이 종속성을 표현하려면 WaitFor 메서드를 사용합니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
       .WithReference(postgresdb)
       .WaitFor(postgresdb);

앞의 코드에서 "apiservice" 프로젝트 리소스는 "postgresdb" 데이터베이스 리소스가 KnownResourceStates.Running 상태가 될 때까지 기다립니다. 예제 코드는 .NET AspirePostgreSQL 통합보여 주지만 다른 리소스에도 동일한 패턴을 적용할 수 있습니다.

종속 리소스가 시작되기 전에 다른 경우에는 KnownResourceStates.Exited 또는 KnownResourceStates.Finished 리소스가 완료될 때까지 기다려야 할 수 있습니다. 리소스가 완료될 때까지 기다리려면 WaitForCompletion 메서드를 사용합니다.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var migration = builder.AddProject<Projects.AspireApp_Migration>("migration")
                       .WithReference(postgresdb)
                       .WaitFor(postgresdb);

builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
       .WithReference(postgresdb)
       .WaitForCompletion(migration);

앞의 코드에서 "apiservice" 프로젝트 리소스는 시작하기 전에 "마이그레이션" 프로젝트 리소스가 완료될 때까지 기다립니다. "마이그레이션" 프로젝트 리소스는 "postgresdb" 데이터베이스 리소스가 KnownResourceStates.Running 상태가 될 때까지 기다립니다. 예를 들어 API 서비스를 시작하기 전에 데이터베이스 마이그레이션을 실행하려는 시나리오에서 유용할 수 있습니다.

대시보드에서 리소스 강제 시작

대시보드에서 시작 명령을 사용하여 리소스 대기를 무시할 수 있습니다. 대시보드에서 대기 중인 리소스에서 시작을 선택하면 리소스가 정상 상태가 되거나 완료될 때까지 기다리지 않고 즉시 시작하도록 지시합니다. 리소스를 즉시 테스트하고 앱이 올바른 상태가 될 때까지 기다리지 않으려는 경우에 유용할 수 있습니다.

리소스 추가 및 표현을 위한 API

.NET .NET Aspire 호스팅 통합 및 클라이언트 통합 둘 다 NuGet 패키지로 제공되지만 서로 다른 용도로 사용됩니다. 클라이언트 통합은 앱 호스트의 범위를 벗어난 앱에서 클라이언트 라이브러리를 구성하여 사용할 수 있도록 제공하는 반면에, 호스팅 통합은 앱 호스트 내에서 리소스 및 종속성을 표현할 수 있는 API를 제공합니다. 자세한 내용은 .NET.NET Aspire 통합 개요: 통합 책임참조하세요.

컨테이너 리소스를 표현하다

ContainerResource 표현하려면 IDistributedApplicationBuilder 메서드를 호출하여 AddContainer 인스턴스에 추가합니다.

Docker
Podman

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithBindMount("ollama", "/root/.ollama")
    .WithBindMount("./ollamaconfig", "/usr/config")
    .WithHttpEndpoint(port: 11434, targetPort: 11434, name: "ollama")
    .WithEntrypoint("/usr/config/entrypoint.sh")
    .WithContainerRuntimeArgs("--gpus=all");

자세한 내용은 GPU 지원을 Docker Desktop에서 참조하세요.

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithBindMount("ollama", "/root/.ollama")
    .WithBindMount("./ollamaconfig", "/usr/config")
    .WithHttpEndpoint(port: 11434, targetPort: 11434, name: "ollama")
    .WithEntrypoint("/usr/config/entrypoint.sh")
    .WithContainerRuntimeArgs("--device", "nvidia.com/gpu=all");

자세한 내용은 GPU 지원을 Podman에서 참조하세요.

위의 코드는 이미지 번호 ollama/ollama와 함께 "ollama"라는 이름의 컨테이너 리소스를 추가합니다. 컨테이너 리소스는 여러 바인드 마운트, 명명된 HTTP 엔드포인트, Unix 셸 스크립트로 연결되는 시작점, 및 WithContainerRuntimeArgs 메서드를 사용하는 컨테이너 실행 인수로 구성됩니다.

컨테이너 리소스 사용자 지정

모든 ContainerResource 서브클래스는 특정 요구 사항을 충족하도록 사용자 지정할 수 있습니다. 컨테이너 리소스를 모델화하지만 수정이 필요한 호스팅 통합 사용할 때 유용할 수 있습니다. IResourceBuilder<ContainerResource> 있는 경우 사용 가능한 API에 대한 호출을 연결하여 컨테이너 리소스를 수정할 수 있습니다. .NET .NET Aspire 컨테이너 리소스는 일반적으로 고정된 태그를 가리키지만 대신 latest 태그를 사용할 수 있습니다.

이를 설명하기 위해 .NET AspireRedis 통합사용하는 시나리오를 상상해 보십시오. Redis 통합이 7.4 태그에 의존하고 있으며, 대신 latest 태그를 사용하고자 한다면 WithImageTag API에 호출을 연결할 수 있습니다.

var builder = DistributedApplication.CreateBuilder(args);

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

// Instead of using the "7.4" tag, the "cache" 
// container resource now uses the "latest" tag.

자세한 내용 및 사용 가능한 추가 API는 ContainerResourceBuilderExtensions참조하세요.

컨테이너 리소스 수명 주기

앱 호스트가 실행되면 ContainerResource 사용하여 만들고 시작할 컨테이너 이미지를 결정합니다. 시스템은 내부적으로 .NET Aspire가 OCI 규격을 준수하는 컨테이너 런타임(Docker 또는 Podman)에 대한 호출을 위임하여, 정의된 컨테이너 이미지를 사용해 컨테이너를 실행합니다. 다음 명령이 사용됩니다.

Docker
Podman

먼저 docker container create 명령을 사용하여 컨테이너를 만듭니다. 그런 다음 컨테이너가 docker container start 명령을 사용하여 시작됩니다.

docker 컨테이너 만들기 : 지정된 이미지에서 새 컨테이너를 시작하지 않고 만듭니다.
docker 컨테이너 시작: 하나 이상의 중지된 컨테이너를 시작합니다.

이러한 명령은 연결된 컨테이너 네트워크, 볼륨 및 포트를 관리하기 위해 docker run 대신 사용됩니다. 이 순서대로 이러한 명령을 호출하면 초기 시작 시 모든 IP(네트워크 구성)가 이미 존재할 수 있습니다.

먼저 podman container create 명령을 사용하여 컨테이너를 만듭니다. 그런 다음 컨테이너가 podman container start 명령을 사용하여 시작됩니다.

Podman 컨테이너 만들기: 지정된 이미지 위에 쓰기 가능한 컨테이너 계층을 만들고 실행을 준비합니다.
Podman 컨테이너 시작: 하나 이상의 중지된 컨테이너를 실행합니다.

이러한 명령은 연결된 컨테이너 네트워크, 볼륨 및 포트를 관리하기 위해 podman run 대신 사용됩니다. 이 순서대로 이러한 명령을 호출하면 초기 시작 시 모든 IP(네트워크 구성)가 이미 존재할 수 있습니다.

ProjectResource ContainerResource 기본 리소스 종류, ExecutableResource, .NET및 .NET Aspire외에도 앱 모델에 공통 리소스를 추가하는 확장 메서드를 제공합니다. 자세한 내용은 호스팅 통합참조하세요.

컨테이너 리소스 수명

기본적으로 컨테이너 리소스는 세션 컨테이너 수명을 사용합니다. 즉, 앱 호스트 프로세스가 시작될 때마다 컨테이너가 만들어지고 시작됩니다. 앱 호스트가 중지되면 컨테이너가 중지되고 제거됩니다. 컨테이너 리소스는 불필요한 다시 시작을 방지하고 영구적인 컨테이너 상태를 사용하기 위해 영구 수명을 선택할 수 있습니다. 이를 달성하려면 ContainerResourceBuilderExtensions.WithLifetime API를 순차적으로 호출하고 ContainerLifetime.Persistent을 전달하십시오.

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddContainer("ollama", "ollama/ollama")
    .WithLifetime(ContainerLifetime.Persistent);

앞의 코드는 "ollama/ollama" 이미지와 영구 수명이 있는 "ollama"라는 컨테이너 리소스를 추가합니다.

리소스 관계

리소스 관계는 리소스를 함께 연결합니다. 관계는 정보 제공이며 앱의 런타임 동작에 영향을 주지 않습니다. 대신 대시보드에 리소스에 대한 세부 정보를 표시할 때 사용됩니다. 예를 들어 관계는 대시보드의 리소스 세부 정보표시되고 Parent 관계는 리소스 페이지의 리소스 중첩을 제어합니다.

관계는 일부 앱 모델 API에 의해 자동으로 생성됩니다. 다음은 그 예입니다.

WithReference Reference형식을 사용하여 대상 리소스에 관계를 추가합니다.
WaitFor WaitFor형식을 사용하여 대상 리소스에 관계를 추가합니다.
DB 컨테이너에 데이터베이스를 추가하면 데이터베이스에서 Parent형식의 컨테이너로의 관계가 만들어집니다.

WithRelationship 및 WithParentRelationship사용하여 앱 모델에 관계를 명시적으로 추가할 수도 있습니다.

var builder = DistributedApplication.CreateBuilder(args);

var catalogDb = builder.AddPostgres("postgres")
                       .WithDataVolume()
                       .AddDatabase("catalogdb");

builder.AddProject<Projects.AspireApp_CatalogDbMigration>("migration")
       .WithReference(catalogDb)
       .WithParentRelationship(catalogDb);

builder.Build().Run();

앞의 예제에서는 WithParentRelationship 사용하여 catalogdb 데이터베이스를 migration 프로젝트의 부모로 구성합니다. Parent 관계는 리소스 페이지의 리소스 중첩을 제어하기 때문에 특별합니다. 이 예제에서는 migrationcatalogdb아래에 중첩됩니다.

비고

리소스에 부모가 여러 개 있거나 순환 참조를 만들지 못하도록 부모 관계에 대한 유효성 검사가 있습니다. 이러한 구성은 UI에서 렌더링할 수 없으며 앱 모델에서 오류가 발생합니다.