자습서: 기존 .NET Aspire 앱에 .NET 추가

2025-07-04

기존 마이크로 서비스 및 .NET 웹앱이 있는 경우 .NET Aspire 추가하고 포함된 모든 기능과 이점을 얻을 수 있습니다. 이 기사에서는 .NET Aspire 오케스트레이션을 간단하고 기존의 .NET 9 프로젝트에 추가하는 법을 설명합니다. 아래와 같은 방법을 배우게 됩니다.

기존 마이크로 서비스 앱의 구조를 이해합니다.
.NET .NET Aspire 오케스트레이션에 기존 프로젝트를 등록합니다.
프로젝트 등록의 변동이 프로젝트에 미치는 영향을 이해한다.
.NET .NET Aspire 프로젝트를 시작합니다.

필수 구성 요소

.NET .NET Aspire작업하려면 다음을 로컬에 설치해야 합니다.

.NET 8.0 또는 .NET 9.0
OCI 규격을 준수하는 컨테이너 런타임(예:
- Docker 데스크톱 또는 Podman. 자세한 내용은 컨테이너 런타임참조하세요.
IDE(통합 개발자 환경) 또는 코드 편집기(예:
- Visual Studio 2022 버전 17.9 이상(선택 사항)
- Visual Studio Code(선택 사항)
  - C# Dev Kit: 확장(선택 사항)
- JetBrains Rider .NET.NET Aspire 플러그인 (선택 사항)

자세한 내용은 .NET.NET Aspire 설정 및 도구및 .NET.NET Aspire SDK참조하세요.

시작

먼저 솔루션에 대한 코드를 가져와 보겠습니다.

명령 프롬프트를 열고 코드를 저장할 위치로 디렉터리를 변경합니다.

.NET 9 예제 솔루션에 복제하려면 다음 git clone 명령을 사용합니다.

git clone https://github.com/MicrosoftDocs/mslearn-dotnet-cloudnative-devops.git eShopLite

샘플 앱 살펴보기

이 문서에서는 세 개의 프로젝트와 함께 .NET 9 솔루션을 사용합니다.

데이터 엔터티: 이 프로젝트는 예제 클래스 라이브러리입니다. Web App 및 Web API에서 사용되는 Product 클래스를 정의합니다.
제품: 이 예제 Web API는 카탈로그의 제품 목록과 해당 속성을 반환합니다.
스토어: 웹앱이 웹 사이트 방문자에게 제품 카탈로그를 표시하는 Blazor 예제입니다.

샘플 앱 아키텍처

샘플 앱의 구조를 더 잘 이해하려면 간단한 3계층 아키텍처를 보여 주는 다음 다이어그램을 고려하세요.

이 계층화된 디자인은 문제를 명확하게 분리하여 앱을 더 쉽게 유지 관리하고 확장할 수 있도록 합니다.

샘플 앱 실행

프로젝트를 열고 디버깅을 시작하여 기본 동작을 검사합니다.

Visual Studio 시작한 다음 파일>>프로젝트/솔루션엽니다.
복제한 솔루션의 상위 폴더로 이동한 후, eShopLite.sln를 선택하고 열기를 선택합니다.
솔루션 탐색기eShopLite 솔루션을 마우스 오른쪽 단추로 클릭한 다음 시작 프로젝트구성 선택합니다.
여러 시작 프로젝트를 선택하십시오.
작업 열에서 제품 및 스토어 프로젝트 모두에 대해 시작을(를) 선택합니다.
확인선택합니다.
솔루션 디버깅을 시작하려면 F5 누르거나 시작선택합니다.
브라우저에서 두 페이지가 열립니다.
- 페이지에는 Products Web API 호출을 통해 JSON 형식으로 된 제품이 표시됩니다.
- 페이지에는 웹 사이트의 홈페이지가 표시됩니다. 왼쪽 메뉴에서 제품 선택하여 Web API에서 가져온 카탈로그를 확인합니다.
디버깅을 중지하려면 브라우저를 닫습니다.

Visual Studio Code을 시작하고 복제한 폴더를 엽니다. 리포지토리를 복제한 터미널에서 다음 명령을 실행합니다.
```
code .
```
실행 및 디버그 메뉴 항목을 선택하거나 Ctrl+Shift+D키를 누릅니다.
launch.json 파일 생성하기 링크를 선택합니다.

다음 JSON을 이 파일에 복사하여 붙여넣고 저장하세요.

Unix
windows

{
    "version": "0.2.0",
    "compounds": [
        {
            "name": "Run all",
            "configurations": [
                "Run products",
                "Run store",
            ]
        }
    ],
    "configurations": [
        {
            "name": "Run products",
            "type": "dotnet",
            "request": "launch",
            "projectPath": "${workspaceFolder}/Products/Products.csproj"
        },
        {
            "name": "Run store",
            "type": "dotnet",
            "request": "launch",
            "projectPath": "${workspaceFolder}/Store/Store.csproj"
        }
    ]
}

{
    "version": "0.2.0",
    "compounds": [
        {
            "name": "Run all",
            "configurations": [
                "Run products",
                "Run store",
            ]
        }
    ],
    "configurations": [
        {
            "name": "Run products",
            "type": "dotnet",
            "request": "launch",
            "projectPath": "${workspaceFolder}\\Products\\Products.csproj"
        },
        {
            "name": "Run store",
            "type": "dotnet",
            "request": "launch",
            "projectPath": "${workspaceFolder}\\Store\\Store.csproj"
        }
    ]
}

솔루션 디버깅을 시작하려면 F5 누르거나 시작선택합니다.
브라우저에서 두 페이지가 열립니다.
- 페이지에는 Products Web API 호출을 통해 JSON 형식으로 된 제품이 표시됩니다.
- 페이지에는 웹 사이트의 홈페이지가 표시됩니다. 왼쪽 메뉴에서 제품 선택하여 Web API에서 가져온 카탈로그를 확인합니다.
디버깅을 중지하려면 브라우저를 닫은 다음 중지 단추를 두 번 선택합니다(실행 중인 디버그 인스턴스마다 한 번).

터미널 창을 열고 디렉터리를 새로 복제된 리포지토리로 변경합니다.
Products 앱을 시작하려면 다음 명령을 실행합니다.
```
dotnet run --project ./Products/Products.csproj
```
제품의 JSON을 표시하는 브라우저 페이지가 열립니다.
별도의 터미널 창에서 디렉터리를 복제된 리포지토리로 다시 변경합니다.
다음 명령을 실행하여 Store 앱을 시작합니다.
```
dotnet run --project ./Store/Store.csproj
```
브라우저에서 웹 사이트의 홈페이지를 표시하는 페이지를 엽니다. 왼쪽 메뉴에서 제품 선택하여 Web API에서 가져온 카탈로그를 확인합니다.
디버깅을 중지하려면 브라우저를 닫고 두 터미널에서 Ctrl+C 누릅니다.

어떤 도구를 사용하든, 여러 프로젝트를 수동으로 시작하거나 이들 간의 연결을 구성하는 것은 지루합니다. 또한 Store 프로젝트에는 번거롭고 오류가 발생하기 쉬운 Products API에 대한 명시적 엔드포인트 구성이 필요합니다. 이곳에서 .NET.NET Aspire 프로세스를 단순화하고 간소화합니다!

템플릿이 설치되어 있는지 확인 .NET.NET Aspire

이전에 현재 컴퓨터에서 작업한 .NET Aspire 적이 있는 경우 필요한 .NET 프로젝트 템플릿이 이미 설치되어 있을 수 있습니다. 다음 명령을 사용하여 확인할 수 있습니다.

dotnet new list aspire

템플릿이 .NET.NET Aspire 설치된 경우 출력은 다음과 유사합니다.

These templates matched your input: '.NET Aspire'

Template Name       Short Name              Language  Tags
------------------  ----------------------  --------  -------------------------------------------------------------------------------
.NET Aspire App...  aspire-apphost          [C#]      Common/.NET Aspire/Cloud
.NET Aspire Emp...  aspire                  [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service
.NET Aspire Ser...  aspire-servicedefaults  [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service
.NET Aspire Sta...  aspire-starter          [C#]      Common/.NET Aspire/Blazor/Web/Web API/API/Service/Cloud/Test/MSTest/NUnit/xUnit
.NET Aspire Tes...  aspire-mstest           [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service/Test/MSTest
.NET Aspire Tes...  aspire-nunit            [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service/Test/NUnit
.NET Aspire Tes...  aspire-xunit            [C#]      Common/.NET Aspire/Cloud/Web/Web API/API/Service/Test/xUnit

이 자습서에서는 App Host 프로젝트와 서비스 기본값 프로젝트를 추가합니다.

이전 명령에서 템플릿을 찾지 못한 경우 설치해야 합니다. 다음 명령을 실행합니다.

dotnet new install Aspire.ProjectTemplates

템플릿에 대한 .NET.NET Aspire 자세한 내용은 템플릿을 참조 .NET.NET Aspire 하세요.

스토어 웹앱에 .NET.NET Aspire 추가

이제 웹 사용자 인터페이스를 구현하는 Store 프로젝트를 .NET.NET Aspire 오케스트레이션에 등록해 보겠습니다.

Visual Studio 솔루션 탐색기에서 스토어 프로젝트를 우클릭한 후, 추가를 선택하고, 그리고 .NET.NET Aspire Orchestrator 지원을 선택합니다.
.NET .NET Aspire Orchestrator 지원 추가 대화 상자에서 확인을 선택합니다.

이제 솔루션에 두 개의 새 프로젝트가 추가되었습니다.

eShopLite.AppHost: 앱의 다양한 프로젝트와 서비스를 연결하고 구성하도록 설계된 오케스트레이터 프로젝트입니다. 오케스트레이터는 시작 프로젝트로 설정되며, eShopLite.Store 프로젝트에 의존합니다.
eShopLite.ServiceDefaults: .NET.NET Aspire 여러분의 솔루션 내 여러 프로젝트에서 복원력, 서비스 검색 및 원격 분석과 관련된 설정을 관리하기 위한 공유 프로젝트입니다.

eShopLite.AppHost 프로젝트에서 Program.cs 파일을 엽니다. .NET 오케스트레이션에 .NET Aspire 프로젝트를 등록하는 이 코드 줄을 확인합니다.

builder.AddProject<Projects.Store>("store");

자세한 내용은 AddProject를 참조하세요.

Products 프로젝트를 .NET.NET Aspire추가하려면 다음을 수행합니다.

Visual Studio 솔루션 탐색기에서 제품 프로젝트를 마우스 오른쪽 단추로 클릭하고 추가를 선택한 다음, .NET.NET Aspire Orchestrator 지원을 선택합니다.
.NET .NET Aspire Orchestrator 프로젝트가 이미 있음을 나타내는 대화 상자에서 확인선택합니다.

.NET .NET Aspire Orchestrator가 이미 추가되었음을 나타내는

eShopLite.AppHost 프로젝트에서 Program.cs 파일을 엽니다. .NET 오케스트레이션에서 .NET Aspire 프로젝트를 등록하는 이 코드 줄을 확인합니다.

builder.AddProject<Projects.Products>("products");

또한 eShopLite.AppHost 프로젝트는 이제 Store 프로젝트와 Products 프로젝트에 의존하게 되었습니다.

앱 호스트 프로젝트 만들기

기존 프로젝트를 오케스트레이션하려면 새 앱 호스트 프로젝트를 만들어야 합니다. 사용 가능한 템플릿에서 새 만들려면 다음 .NET Aspire CLI 명령을 사용합니다.

dotnet new aspire-apphost -o eShopLite.AppHost

앱 호스트 프로젝트를 기존 솔루션에 추가합니다.

Unix
windows

dotnet sln ./eShopLite.sln add ./eShopLite.AppHost/eShopLite.AppHost.csproj

dotnet sln .\eShopLite.sln add .\eShopLite.AppHost\eShopLite.AppHost.csproj

다음 CLI 명령을 사용하여 스토어 프로젝트를 .NET 프로젝트에 대한 프로젝트 참조로 추가합니다.

Unix
windows

dotnet add ./eShopLite.AppHost/eShopLite.AppHost.csproj reference ./Store/Store.csproj

dotnet add .\eShopLite.AppHost\eShopLite.AppHost.csproj reference .\Store\Store.csproj

사용 가능한 템플릿에 대한 자세한 내용은 템플릿을 참조하세요.

서비스 기본 프로젝트 만들기

앱 호스트 프로젝트를 만든 후 새 서비스 기본값 프로젝트를 만들어야 합니다. 새 서비스 기본값 프로젝트를 사용 가능한 .NET Aspire 템플릿에서 생성하려면 다음 .NET CLI 명령을 사용합니다.

dotnet new aspire-servicedefaults -o eShopLite.ServiceDefaults

솔루션에 프로젝트를 추가하려면 다음 .NET CLI 명령을 사용합니다.

Unix
windows

dotnet sln ./eShopLite.sln add ./eShopLite.ServiceDefaults/eShopLite.ServiceDefaults.csproj

dotnet sln .\eShopLite.sln add .\eShopLite.ServiceDefaults\eShopLite.ServiceDefaults.csproj

앱 호스트 프로젝트를 업데이트하여 Products 프로젝트에 프로젝트 참조를 추가합니다.

Unix
windows

dotnet add ./eShopLite.AppHost/eShopLite.AppHost.csproj reference ./Products/Products.csproj

dotnet add .\eShopLite.AppHost\eShopLite.AppHost.csproj reference .\Products\Products.csproj

스토어 및 제품 프로젝트는 모두 서비스 기본 프로젝트를 참조하여 서비스 검색을 쉽게 포함할 수 있도록 해야 합니다. Store 프로젝트에서 서비스 기본값이 있는 프로젝트에 참조를 추가하려면 다음 .NET CLI 명령을 사용합니다.

Unix
windows

dotnet add ./Store/Store.csproj reference ./eShopLite.ServiceDefaults/eShopLite.ServiceDefaults.csproj

dotnet add .\Store\Store.csproj reference .\eShopLite.ServiceDefaults\eShopLite.ServiceDefaults.csproj

경로가 약간 다른 동일한 명령을 사용하여 Products 프로젝트의 서비스 기본 프로젝트에 대한 참조를 추가해야 합니다.

Unix
windows

dotnet add ./Products/Products.csproj reference ./eShopLite.ServiceDefaults/eShopLite.ServiceDefaults.csproj

dotnet add .\Products\Products.csproj reference .\eShopLite.ServiceDefaults\eShopLite.ServiceDefaults.csproj

Store와 상품 프로젝트에서 Program.cs 파일을 업데이트하고 var builder = WebApplication.CreateBuilder(args); 줄 바로 다음에 다음 줄을 추가합니다.

builder.AddServiceDefaults();

앱 호스트 프로젝트 업데이트

Program.cs 프로젝트의 파일을 열고 해당 내용을 다음 C# 코드로 바꿉니다.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.Store>("store");

builder.AddProject<Projects.Products>("products");

builder.Build().Run();

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

새 DistributedApplicationBuilder 인스턴스를 만듭니다.
오케스트레이터에 Store 프로젝트를 추가합니다.
Products 프로젝트를 오케스트레이터에 추가합니다.
오케스트레이터를 빌드하고 실행합니다.

서비스 검색

이 시점에서 두 프로젝트는 모두 .NET.NET Aspire 오케스트레이션의 일부이지만 Store 프로젝트는 통해 .NET 백 엔드 주소에 의존해야 합니다. 서비스 검색을 사용하도록 설정하려면 Program.cs 프로젝트에서 파일을 열고 builderProducts 프로젝트에 대한 참조를 추가하도록 코드를 업데이트합니다.

var builder = DistributedApplication.CreateBuilder(args);

var products = builder.AddProject<Projects.Products>("products");

builder.AddProject<Projects.Store>("store")
       .WithExternalHttpEndpoints()
       .WithReference(products)
       .WaitFor(products);

builder.Build().Run();

앞의 코드는 Store 프로젝트가 Products 프로젝트에 종속되어 있음을 표시합니다. 자세한 내용은 .NET.NET Aspire 앱 호스트:참조 리소스를 참조하세요. 이 참조는 런타임에 Products 프로젝트의 주소를 검색하는 데 사용됩니다. 또한 Store 프로젝트는 외부 HTTP 엔드포인트를 사용하도록 구성됩니다. 나중에 이 앱을 배포하도록 선택하는 경우 외부 세계에 공개되도록 WithExternalHttpEndpoints 호출이 필요합니다. 마지막으로, API는 WaitForStore 앱이 제품 앱이 요청을 처리할 준비가 될 때까지 대기하도록 합니다.

다음으로, appsettings.json 프로젝트에서 을 다음 JSON으로 업데이트합니다.

{
  "DetailedErrors": true,
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ProductEndpoint": "http://products",
  "ProductEndpointHttps": "https://products"
}

두 엔드포인트의 주소는 이제 앱 호스트오케스트레이터에 추가된 "제품" 이름을 사용합니다. 이러한 이름은 Products 프로젝트의 주소를 검색하는 데 사용됩니다.

등록된 앱 탐색

솔루션을 시작하고 .NET.NET Aspire 제공하는 새 동작을 살펴보겠습니다.

메모

eShopLite.AppHost 프로젝트는 새 시작 프로젝트입니다.

Visual Studio디버깅을 시작하려면 F5 키를 누릅니다.프로젝트 빌드는Visual Studio에서 수행됩니다.
시작 Docker 바탕 화면 대화 상자가 나타나면 예선택합니다. Visual Studio Docker 엔진을 시작하고 필요한 컨테이너를 만듭니다. 배포가 완료되면 .NET.NET Aspire 대시보드가 표시됩니다.
대시보드에서 제품 프로젝트의 엔드포인트를 선택합니다. 새 브라우저 탭이 나타나고 제품 카탈로그가 JSON 형식으로 표시됩니다.
대시보드에서 저장소 프로젝트의 엔드포인트를 선택합니다. 새 브라우저 탭이 나타나고 웹앱의 홈페이지가 표시됩니다.
왼쪽 메뉴에서 제품 선택합니다. 제품 카탈로그가 표시됩니다.
디버깅을 중지하려면 브라우저를 닫습니다.

이전에 만든 launch.json 파일을 삭제하면 더 이상 용도로 사용할 수 없습니다. 대신 다른 프로젝트를 오케스트레이션하는 앱 호스트 프로젝트를 시작합니다.

솔루션 탐색기eShopLite.AppHost 프로젝트를 마우스 오른쪽 단추로 클릭하고 디버그>선택하여 앱 호스트 프로젝트를 시작합니다.

메모

Docker Desktop(또는 Podman)이 실행되고 있지 않으면 오류가 발생합니다. 컨테이너 런타임을 시작하고 다시 시도합니다.

다음 명령을 실행하여 앱 호스트 프로젝트를 시작합니다.
```
dotnet run --project ./eShopLite.AppHost/eShopLite.AppHost.csproj
```
메모

Docker Desktop(또는 Podman)이 실행되고 있지 않으면 오류가 발생합니다. 컨테이너 런타임을 시작하고 다시 시도합니다.

대시보드에서 제품 프로젝트의 엔드포인트를 선택합니다. 새 브라우저 탭이 나타나고 제품 카탈로그가 JSON 형식으로 표시됩니다.
대시보드에서 저장소 프로젝트의 엔드포인트를 선택합니다. 새 브라우저 탭이 나타나고 웹앱의 홈페이지가 표시됩니다.
왼쪽 메뉴에서 제품 선택합니다. 제품 카탈로그가 표시됩니다.
디버깅을 중지하려면 브라우저를 닫습니다.

축하합니다. 기존 웹앱에 오케스트레이션을 추가 .NET.NET Aspire 했습니다. 이제 .NET Aspire 통합을 추가하고 .NET Aspire 도구를 사용하여 클라우드 네이티브 웹앱 개발을 간소화할 수 있습니다.