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

2025-07-29

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

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

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

리소스 명명 규칙

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

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" 에서 리소스는 분산 애플리케이션으로 자동으로 시작되지 않도록 구성됩니다.

Aspire 대시보드에서 "시작" 명령을 클릭하면 명시적으로 시작할 수 있는 리소스를 시작할 수 있습니다. 자세한 내용은 대시보드: 리소스 중지 또는 시작을 참조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 상태가 될 때까지 기다립니다. 예제 코드는 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

Aspire 호스팅 통합 및 클라이언트 통합 은 모두 NuGet 패키지로 제공되지만 서로 다른 용도로 사용됩니다. 클라이언트 통합은 앱 호스트의 범위를 벗어난 앱에서 클라이언트 라이브러리를 구성하여 사용할 수 있도록 제공하는 반면에, 호스팅 통합은 앱 호스트 내에서 리소스 및 종속성을 표현할 수 있는 API를 제공합니다. 자세한 내용은 통합 개요: 통합 책임을 참조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에 대한 호출을 연결하여 컨테이너 리소스를 수정할 수 있습니다. Aspire 컨테이너 리소스는 일반적으로 고정된 태그를 가리키지만 대신 태그를 latest 사용할 수 있습니다.

이를 설명하기 위해 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 사용하여 만들고 시작할 컨테이너 이미지를 결정합니다. 시스템은 내부적으로 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 ExecutableResourceAspire 외에도 앱 모델에 공통 리소스를 추가하는 확장 메서드를 제공합니다. 자세한 내용은 호스팅 통합참조하세요.

컨테이너 리소스 수명

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

Express 외부 서비스 리소스

외부 서비스는 애플리케이션이 종속되지만 솔루션 외부 Aspire 에 존재하는 타사 API 및 서비스입니다. 이러한 서비스는 이미 다른 곳에서 실행 중이며 관리 Aspire되지 않습니다. ExternalServiceResource을(를) 표현하기 위해, AddExternalService 메서드를 호출하여 IDistributedApplicationBuilder 인스턴스에 추가합니다.

var builder = DistributedApplication.CreateBuilder(args);

var nuget = builder.AddExternalService("nuget", "https://api.nuget.org/")
    .WithHttpHealthCheck(path: "/v3/index.json");

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(nuget);

앞의 코드는 NuGet API를 가리키는 "nuget"이라는 외부 서비스 리소스를 추가합니다. 외부 서비스는 HTTP 상태 검사를 사용하여 가용성을 모니터링하도록 구성됩니다. 프런트 엔드 프로젝트는 서비스 검색을 위해 이 외부 서비스를 참조할 수 있습니다.

외부 서비스는 다음과 같은 몇 가지 구성 방법을 지원합니다.

정적 URL 구성

문자열 또는 URI를 사용하여 정적 URL로 외부 서비스를 구성할 수 있습니다.

var builder = DistributedApplication.CreateBuilder(args);

// Using a string URL
var nuget = builder.AddExternalService("nuget", "https://api.nuget.org/");

// Using a URI
var uri = new Uri("https://api.example.com/");
var api = builder.AddExternalService("external-api", uri);

매개 변수 기반 URL 구성

외부 서비스 URL이 환경마다 다르거나 구성할 수 있어야 하는 시나리오의 경우 매개 변수를 사용할 수 있습니다.

var builder = DistributedApplication.CreateBuilder(args);

var externalServiceUrl = builder.AddParameter("external-service-url");
var externalService = builder.AddExternalService("external-service", externalServiceUrl);

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(externalService);

매개 변수 기반 구성을 사용하는 경우 URL 값은 구성, 환경 변수 또는 사용자 비밀을 통해 설정할 수 있습니다. 개발 중인 Aspire에서 URL 값을 제공하라는 메시지가 표시될 수 있습니다. 자세한 내용은외부 매개 변수를 참조하세요.

외부 서비스 URL 요구 사항

외부 서비스 URL은 특정 요구 사항을 충족해야 합니다.

절대 URI(구성표, 호스트 및 선택적 포트 포함)여야 합니다.
절대 경로가 "/"로 설정되어 있어야 합니다(추가 경로 세그먼트 없음).
쿼리 매개 변수 또는 조각을 포함해서는 안 됩니다.

Valid examples:

https://api.example.com/
http://localhost:8080/
https://service.example.com:9443/

Invalid examples:

https://api.example.com/v1/api (경로 포함)
https://api.example.com/?version=1 (쿼리 포함)
https://api.example.com/#section (조각 포함)

외부 서비스에 대한 상태 검사

HTTP 상태 검사를 사용하여 외부 서비스를 구성하여 가용성을 모니터링할 수 있습니다.

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddExternalService("api", "https://api.example.com/")
    .WithHttpHealthCheck(path: "/health", statusCode: 200);

이 메서드는 WithHttpHealthCheck 외부 서비스를 주기적으로 폴링하는 상태 검사를 추가합니다. 다음을 지정할 수 있습니다.

path: 상태 검사 엔드포인트의 상대 경로입니다(선택 사항, 기본값은 추가 경로 없음).
statusCode: 예상 HTTP 상태 코드(선택 사항, 기본값: 200)입니다.

외부 서비스를 사용하여 서비스 검색

다른 리소스 Aspire 에서 외부 서비스를 참조하는 경우 환경 변수를 표준 형식으로 삽입하여 서비스 검색을 자동으로 구성합니다.

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddExternalService("api", "https://api.example.com/");

var frontend = builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(api);

이 구성은 프런트 엔드 프로젝트와 같은 services__api__https__0=https://api.example.com/ 환경 변수를 삽입하여 표준 .NET 서비스 검색 메커니즘을 통해 서비스 검색을 사용하도록 설정합니다.

외부 서비스 수명 주기

외부 서비스는 IResourceWithoutLifetime를 구현하며, 이는 Aspire의 수명 주기 시스템에서 관리되지 않음을 의미합니다. 독립적으로 실행될 것으로 예상됩니다. 개발 중에 외부 서비스는 연결할 수 있는 경우 "실행 중" 상태로 대시보드에 Aspire 표시되거나, 사용할 수 없는 경우 상태 검사 실패를 표시합니다.

Resource relationships

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

관계는 일부 앱 모델 API에 의해 자동으로 생성됩니다. For example:

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아래에 중첩됩니다.

Note

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