Aspire 13.2: .NET 서비스 개발자가 알아야 할 사항

핵심 요약

• CLI가 이제 진정으로 스크립트 가능함: 분리 모드, aspire ps, aspire 중단, 격리 모드, JSON 출력
• TypeScript AppHost는 오케스트레이션 레이어용 .csproj를 버리고 싶다면 사전 보기 상태입니다.
• 구성 파일이 aspire.config.json로 통합됨 (레거시 파일은 자동으로 마이그레이션됨)
• Foundry는 Azure AI Foundry를 대체합니다. 이것은 당신의 빌드를 망칠 것입니다.
• WithSecretBuildArg은(는) WithBuildSecret으로 이름이 변경되었습니다.
• 서비스 검색 환경 변수는 이제 끝점 이름이 아니라 스킴을 사용합니다 (조용한 중단 위험)
• 클라이언트 통합에서 기본 Azure 자격 증명 동작이 변경되었습니다.

CLI가 마침내 CLI가 되었다

이것이 헤드라인입니다. 13.2 이전, aspire run는 터미널을 차단하고 대시보드는 실행 중인 AppHost를 관리할 수 있는 유일한 현실적인 표면이었습니다. 단독 개발자에게는 괜찮지만, CI, 통합 테스트 또는 에이전트 주도 워크플로우에는 불편했습니다.

13.2는 이를 수정합니다:

# Run in the background
aspire run --detach

# Or the new shortcut
aspire start

# See what's running
aspire ps

# Stop it
aspire 중단
aspire 중단 --all

# Run in the background
aspire run --detach

# Or the new shortcut
aspire start

# See what's running
aspire ps

# Stop it
aspire 중단
aspire 중단 --all

stdout으로 이동하는 --format json과 함께 (상태 메시지는 stderr로 이동하므로 중요한 경우), 이 주위에 실제 자동화를 구축할 수 있습니다. aspire ps --resources --format json는 에디터 통합 및 스크립트에 대한 견고한 빌딩 블록입니다.

aspire run --isolated
aspire start --isolated

aspire run --isolated
aspire start --isolated

aspire resource api restart
aspire resource api rebuild

aspire resource api restart
aspire resource api rebuild

aspire certs clean
aspire certs trust

aspire secret set ApiKey super-secret-value
aspire secret list --format json

aspire certs clean
aspire certs trust

aspire secret set ApiKey super-secret-value
aspire secret list --format json

aspire wait api --status healthy --timeout 120

aspire wait api --status healthy --timeout 120

로그를 위한 구성: 하나의 파일로 모든 것을 통제

Aspire는 구성 파일을 통합하고 있다. .aspire/settings.json과 apphost.run.json 사이의 옛날 분할은 사라지고, 프로젝트 루트에 단일 aspire.config.json로 대체되었습니다:

{
  "appHost": {
    "path": "apphost.ts",
    "language": "typescript/nodejs"
  },
  "sdk": { "version": "13.2.0" },
  "channel": "stable",
  "profiles": {
    "default": {
      "applicationUrl": "https://localhost:17000;http://localhost:15000"
    }
  }
}

이동은 자동적이다. 기존 프로젝트에서 어떤 aspire 명령이라도 처음 실행할 때, 이전 파일들은 새로운 형식으로 병합되고 경로는 프로젝트 루트로 재기반된다. 레거시 파일은 보존되어 여전히 이전 CLI 버전을 병행 사용할 수 있습니다. 전역 설정 (globalsettings.json) 역시 마이그레이션됩니다.

.aspire/settings.json 또는 apphost.run.json에 직접 접근하는 자동화가 있는 경우, 이동 계획을 세우십시오.

TypeScript AppHost (미리보기)

당신이 첫날에 사용하지 않을지라도 이것은 흥미롭다. 이제 C# 대신 TypeScript에서 앱호스트를 작성할 수 있다:

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cache = await builder.addRedis("cache");

const api = await builder.addProject("api", "../api")
    .withReference(cache)
    .waitFor(cache);

await builder.build().run();

속에서는 TS 앱호스트가 로컬 전송에서 JSON-RPC로 Aspire의 .NET 오케스트레이션 호스트와 통신하며 게스트 프로세스로 실행된다. 동일한 리소스 모델, 동일한 대시보드, 동일한 통합, 단지 TypeScript으로 표현되었다.

흥미로운 부분은 코드 생성이다. aspire add를 실행하면 CLI가 통합의 .NET 어셈블리를 검사하고 .modules/에 TypeScript SDK를 생성합니다. aspire restore은(는) 이를 재생성하며, 업그레이드 후 또는 브랜치 전환 후 유용합니다 (또한 aspire run에서 자동으로 실행됨). 13.2 생성기는 또한 Go, Java, 그리고 Rust 테스트 대상들을 추가하여, 이것이 어디로 향하고 있는지를 의미한다.

.NET-first 팀과 같은 우리에게 이것은 '지켜봐라'보다 '보내라'이지만, 코드 생성 패턴은 향후 다국어 앱호스트 언어들이 모두 동일한 모델을 따르도록 한다. 호스트 브리지가 작동하는 방법에 대해 다국어 아키텍처 문서를 참조하십시오.

대시보드: 원격 강제 판이 새로운 장난감이다

대시보드에 실제 추출/가져오기 워크플로우가 생겼다. 설정 → 관리에서 리소스와 원격 강제 유형을 선택하고 그것들을 zip 형태의 JSON으로 추출한다. 나중에 대시보드로 다시 가져오거나 분석을 위해 다른 사람(또는 LLM)에게 전송하십시오.

aspire export CLI 명령은 동일한 번들을 생성합니다:

aspire export --output .\artifacts\aspire-export.zip
aspire export <resource>

aspire export --output .\artifacts\aspire-export.zip
aspire export <resource>

버그 보고서에 진정으로 유용하다. '여기 몇 장의 스크린샷과 로그 파일이 있습니다' 대신, 실제 원격 강제 상태의 스냅샷을 첨부할 수 있다.

다른 대시보드 측 노트:

• 이제 대시보드 UI에서 리소스 매개변수를 직접 설정할 수 있으며, 사용자 비밀에 지속 시킬 수 있는 옵션이 있다
• 리소스 세부 사항 보기에서 환경 변수를 .env 파일로 내보낼 수 있습니다.
• 리소스 그래프 레이아웃은 적응형 포스 지향 위치를 사용한다. 복잡한 그래프는 눈에 띄게 덜 협잡하다
• /api/telemetry에서 텔레메트리 HTTP API는 OTLP JSON을 반환합니다; NDJSON 스트리밍에 대해서는 ?follow=true을(를) 지원합니다. 엔드포인트는 리소스, 스팬, 로그 및 트레이스를 포함하며, 전체 트레이스 조회를 위한 /traces/{traceId}을(를) 포함합니다.

단독 대시보드는 이제 기본적으로 원격 강제 API를 off로 한다. 대시보드를 직접 호스팅하고 API에 의존하는 경우, DASHBOARD__API__ENABLED=true 플러스 인증 구성 (DASHBOARD__API__AUTHMODE 및 DASHBOARD__API__PRIMARYAPIKEY)이 필요합니다. AppHost와 통합된 시나리오는 여전히 작동하며, 이는 Aspire.Hosting가 자동으로 API를 툴링에 연결하기 때문입니다.

기억할만한 앱 모델 비트

var api = builder.AddProject<Projects.MyApi>("api")
    .WithMcpServer("/mcp");

var api = builder.AddProject<Projects.MyApi>("api")
    .WithMcpServer("/mcp");

Dim api = builder.AddProject(Of Projects.MyApi)("api") _
    .WithMcpServer("/mcp")

var endpoint = redis.GetEndpoint("tcp");

var url = await endpoint.GetValueAsync(new ValueProviderContext {
    Caller = containerApp.Resource,
});

var endpoint = redis.GetEndpoint("tcp");

var url = await endpoint.GetValueAsync(new ValueProviderContext {
    Caller = containerApp.Resource,
});

Dim endpoint = redis.GetEndpoint("tcp")

Dim url = Await endpoint.GetValueAsync(New ValueProviderContext With {
    .Caller = containerApp.Resource
})

builder.AddContainer("worker", "contoso/worker")
    .WithDockerfile("../worker")
    .WithBuildSecret("ACCESS_TOKEN", accessToken);

builder.AddContainer("worker", "contoso/worker")
    .WithDockerfile("../worker")
    .WithBuildSecret("ACCESS_TOKEN", accessToken);

중요한 통합: 중요한 것들

전체 목록은 깁니다. 다음은 내가 주목할 것들이다:

• Docker Compose 배포 이제 안정화되었습니다 (이전에는 프리릴리즈). AddDockerComposeEnvironment은(는) 게시 시점에 앱 모델에서 docker-compose.yaml을(를) 생성합니다. 'Azure에 배포'가 정답이 아닌 경우 유용한 탈출구입니다. IronPDF, IronOCR, 및 IronXL 모두 Linux 컨테이너 및 Docker를 깔끔하게 지원하므로, 생성된 컴포즈 파일은 대개 수동 작업 없이 작동한다는 점을 주목할 가치가 있다.
• Azure Virtual Network 통합(Aspire.Hosting.Azure.Network)은 앱호스트에서 VNets, 서브넷, NSG, NAT 게이트웨이 및 프라이빗 엔드포인트를 선언할 수 있게 해줍니다. AddPrivateEndpoint은(는) 자동으로 프라이빗 DNS 영역, 가상 네트워크 링크를 생성하고 대상에 대한 공용 접근을 비활성화합니다. 이것은 이전에 별도의 Bicep 파일을 유지해야 하는 것과 같은 종류의 것이다.
• Azure Data Lake Storage는 호스팅 및 클라이언트 지원을 받았습니다: AddDataLake, AddDataLakeFileSystem, 그리고 클라이언트 측의 AddAzureDataLakeServiceClient / AddAzureDataLakeFileSystemClient. DI 등록, 재시도, 상태 점검, 텔레메트리, 일반적인 Aspire 스택.
• MongoDB EF Core에는 새로운 클라이언트 통합(Aspire.MongoDB.EntityFrameworkCore)이 있습니다. 일반적인 경우에 AddMongoDbContext<TContext>을(를) 사용하고, DbContext를 직접 등록하는 경우 EnrichMongoDbContext<TContext>()을(를) 사용하십시오.
• Azure AI Inference 이제 임베딩을 챗뿐만 아니라 지원한다. AddAzureEmbeddingsClient("embeddings").AddEmbeddingGenerator()을(를) 등록하고 IEmbeddingGenerator<string, Embedding<float>>을(를) 주입합니다. Keyed 변형도 가능.
• Azure Container Registry는 ACR 정리 작업을 크론 일정에 따라 준비하는 WithPurgeTask("0 1 * * *", ago: TimeSpan.FromDays(7), keep: 5)를 얻었습니다.
• WithBun()를 통해 JavaScript 리소스에 대한 Bun 지원. Yarn 신뢰성은 AddViteApp로 WithYarn()를 통해 고쳐졌습니다.
• Microsoft Foundry가 Azure AI Foundry를 대체한다. Aspire.Hosting.Foundry은(는) Aspire.Hosting.Azure.AIFoundry을(를) 대체합니다. 중단적인 변경; 아래 자세한 내용.

종합하기: Aspire 13.2의 문서 서비스

여기에서 우리는 내부적으로 우리 라이브러리로 분산 시나리오를 테스트하는 패턴을 실행합니다. 이는 대부분의 새로운 13.2 기능이 이러한 유형의 다중 서비스 설정에서 효과가 발휘되지, 장난감 데모에서는 그렇지 않기 때문에 보여줄 만한 가치가 있다.

var builder = DistributedApplication.CreateBuilder(args);

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

// A worker service that uses IronPDF for HTML to PDF rendering
var renderer = builder.AddProject<Projects.PdfRenderer>("renderer")
    .WithReference(cache)
    .WaitFor(cache)
    .WithMcpServer("/mcp");

// An OCR worker that uses IronOCR for image and PDF text extraction
var ocr = builder.AddProject<Projects.OcrWorker>("ocr-worker")
    .WithReference(cache);

// API gateway that fans out to both
builder.AddProject<Projects.Api>("api")
    .WithReference(renderer)
    .WithReference(ocr)
    .WaitFor(renderer)
    .WaitFor(ocr);

builder.Build().Run();

var builder = DistributedApplication.CreateBuilder(args);

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

// A worker service that uses IronPDF for HTML to PDF rendering
var renderer = builder.AddProject<Projects.PdfRenderer>("renderer")
    .WithReference(cache)
    .WaitFor(cache)
    .WithMcpServer("/mcp");

// An OCR worker that uses IronOCR for image and PDF text extraction
var ocr = builder.AddProject<Projects.OcrWorker>("ocr-worker")
    .WithReference(cache);

// API gateway that fans out to both
builder.AddProject<Projects.Api>("api")
    .WithReference(renderer)
    .WithReference(ocr)
    .WaitFor(renderer)
    .WaitFor(ocr);

builder.Build().Run();

Imports DistributedApplication

Dim builder = DistributedApplication.CreateBuilder(args)

Dim cache = builder.AddRedis("cache")

' A worker service that uses IronPDF for HTML to PDF rendering
Dim renderer = builder.AddProject(Of Projects.PdfRenderer)("renderer") _
    .WithReference(cache) _
    .WaitFor(cache) _
    .WithMcpServer("/mcp")

' An OCR worker that uses IronOCR for image and PDF text extraction
Dim ocr = builder.AddProject(Of Projects.OcrWorker)("ocr-worker") _
    .WithReference(cache)

' API gateway that fans out to both
builder.AddProject(Of Projects.Api)("api") _
    .WithReference(renderer) _
    .WithReference(ocr) _
    .WaitFor(renderer) _
    .WaitFor(ocr)

builder.Build().Run()

13.2에서 구체적으로 얻는 것:

• aspire start --isolated을 사용하면 포트 충돌 없이 이 그래프의 두 복사본을 나란히 실행할 수 있습니다. 분기 비교 시 유용하거나 렌더러에 대한 병렬 통합 테스트를 실행할 때
• Razor 템플릿을 변경할 때 전체 그래프를 튕기지 않고 PDF 렌더러만 다시 로드합니다 aspire resource renderer rebuild.
• aspire wait renderer --status healthy --timeout 120은 Chrome 렌더링이 초기화될 때까지 CI가 차단되게 하여 PDF 생성 테스트를 실행하기 전에 대기할 수 있습니다.
• 텔레메트리 HTTP API 및 aspire export은(는) 모든 렌더 호출에 대해 OTLP 포맷의 스팬을 제공합니다. 이는 실제로 느린 CSS 규칙을 프로덕션 트래픽에서 잡아내는 방법입니다.
• WithMcpServer을 사용하면 렌더러를 MCP 도구로 노출하여 코드 에이전트 워크플로우에 유용합니다. 이는 프로그래밍 방식으로 문서를 생성하는 것을 구축할 때 유용합니다.

이와 같은 렌더러 서비스를 구축하고 싶다면, IronPDF의 HTML to PDF 튜토리얼은 C# 측을 안내합니다. OCR 워커에 대해서는, IronOCR 시작 가이드가 기본 사항을 다룹니다.

실제로 물릴 수 있는 중단적인 변경 사항

이를 만날 가능성이 높은 대략적인 순서:

# Before (13.0/13.1)
services__myservice__myendpoint__0 = https://localhost:5001

# After (13.2)
services__myservice__https__0 = https://localhost:5001

# Before (13.0/13.1)
services__myservice__myendpoint__0 = https://localhost:5001

# After (13.2)
services__myservice__https__0 = https://localhost:5001

<PackageReference Include="Aspire.Hosting.Foundry" Version="13.2.0" />

<PackageReference Include="Aspire.Hosting.Foundry" Version="13.2.0" />

// Before
var ai = builder.AddAzureAIFoundry("ai");

// After
var foundry = builder.AddFoundry("ai");
var project = foundry.AddProject("agents");
var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);

// Before
var ai = builder.AddAzureAIFoundry("ai");

// After
var foundry = builder.AddFoundry("ai");
var project = foundry.AddProject("agents");
var chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini);

' Before
Dim ai = builder.AddAzureAIFoundry("ai")

' After
Dim foundry = builder.AddFoundry("ai")
Dim project = foundry.AddProject("agents")
Dim chat = project.AddModelDeployment("chat", FoundryModel.OpenAI.Gpt5Mini)

업그레이드해야 할까요?

로컬에서 다중 서비스 앱을 실행하는 .NET 샵이 원활히 작동하면, 위에서 언급한 중단적인 변경 사항을 전부 고려했다면 그렇습니다. CLI 개선점만으로도 그것은 가치가 있습니다. 분리 모드 및 격리 모드는 특히 실제 워크플로우 문제를 해결합니다.

Foundry 사용자들: 이 릴리스의 새로운 것을 원하는 경우 이름 변경이 강제 마이그레이션이므로 계획을 세우십시오.

TypeScript에 관심 있는 사람들을 위해: 13.2는 TS 앱호스트가 평가할 정도로 충분히 실제가 된 첫 번째 릴리스입니다. 여전히 미리 보기 상태이지만 금요일 오후를 보낼 가치가 있습니다.

이미 13.x에 있는 경우, 업그레이드는 한 줄입니다:

aspire update --self
aspire update

aspire update --self
aspire update

12.x 또는 그 이전에 있는 경우, 먼저 업그레이드 가이드를 참고하십시오. 건너뛰지 못하는 13.0 단계를 포함하고 있습니다.

문서 워크로드와 함께 분산 .NET 앱 구조의 출발점이 되었나요?

서비스들이 PDF 생성, OCR, 엑셀 처리, 바코드 또는 우리가 다루는 다른 포맷을 처리하는 경우, 우리의 라이브러리는 Aspire가 오케스트레이션하는 다중 서비스, 컨테이너 친화적 설정에 맞게 설계되었습니다. 모든 것은 .NET 10, 9, 8, 7, 6, Framework 및 Core를 지원하며, Linux 컨테이너, Azure, AWS 및 온프레미스로 실행됩니다.

시작할 몇 가지 장소:

• IronPDF: HTML을 PDF로 변환, PDF 편집, 서명 및 양식. 튜토리얼 허브는 작동하는 렌더링 서비스를 여는 가장 빠른 경로입니다.
• IronOCR: 125개 이상의 언어에서 이미지 및 PDF 텍스트 추출
• IronXL: Office Interop 없이 Excel 읽기/쓰기
• IronWord: DOCX 생성 및 편집
• IronBarcode 및 IronQR: 바코드 및 QR 코드 생성 및 스캔
• Iron Suite: 위의 기능들 중 두 개 이상이 필요하다면

30일 무료 체험 키 받기하여 Aspire 앱호스트 내에서 1시간 이내에 작동하는 PDF 또는 OCR 서비스를 실행하세요. 문제가 있을 경우, 우리 지원팀은 티켓 처리 대기가 아닌 실제 엔지니어로 구성되어 있습니다.

그게 전부입니다. 다음 릴리스에서 만나요.