.NET .NET Aspire 내부 루프 네트워킹 개요

아티클
12/12/2024

.NET .NET Aspire 사용하여 개발할 때의 이점 중 하나는 클라우드 네이티브 앱을 로컬로 개발, 테스트 및 디버그할 수 있다는 것입니다. 내부 루프 네트워킹은 앱이 개발 환경에서 서로 통신할 수 있도록 하는 .NET.NET Aspire 핵심적인 측면입니다. 이 문서에서는 .NET.NET Aspire 프록시, 엔드포인트, 엔드포인트 구성 및 시작 프로필을 사용하여 다양한 네트워킹 시나리오를 처리하는 방법을 알아봅니다.

내부 루프의 네트워킹

내부 루프는 대상 환경에 배포하기 전에 로컬에서 앱을 개발하고 테스트하는 프로세스입니다. .NET .NET Aspire 다음과 같이 내부 루프에서 네트워킹 환경을 단순화하고 향상시키는 몇 가지 도구와 기능을 제공합니다.

시작 프로필: 시작 프로필은 앱을 로컬로 실행하는 방법을 지정하는 구성 파일입니다. 시작 프로필(예: launchSettings.json 파일)을 사용하여 앱의 엔드포인트, 환경 변수 및 시작 설정을 정의할 수 있습니다.
Kestrel 구성: Kestrel 구성을 사용하면 Kestrel 웹 server 수신 대기하는 엔드포인트를 지정할 수 있습니다. 앱 설정에서 Kestrel 엔드포인트를 구성할 수 있으며, .NET.NET Aspire 자동으로 이러한 설정을 사용하여 엔드포인트를 만들 수 있습니다.
엔드포인트/엔드포인트 구성: 엔드포인트는 앱과 종속되는 서비스(예: 데이터베이스, 메시지 큐 또는 API) 간의 연결입니다. 엔드포인트는 서비스 이름, 호스트 포트, 스키마 및 환경 변수와 같은 정보를 제공합니다. 암시적으로(시작 프로필을 통해) 또는 명시적으로 WithEndpoint호출하여 앱에 엔드포인트를 추가할 수 있습니다.
프록시: .NET.NET Aspire 앱에 추가하는 각 서비스 바인딩에 대해, 프록시를 자동으로 시작하고, 수신 대기할 프록시의 포트를 할당합니다. 그런 다음 프록시는 앱이 수신 대기하는 포트에 요청을 전달합니다. 이는 프록시 포트와 다를 수 있습니다. 이렇게 하면 포트 충돌을 방지하고 일관되고 예측 가능한 URL을 사용하여 앱 및 서비스에 액세스할 수 있습니다.

엔드포인트 작동 방식

.NET .NET Aspire 서비스 바인딩에는 앱에 필요한 외부 리소스를 나타내는 서비스(예: 데이터베이스, 메시지 큐 또는 API) 및 앱과 서비스 간의 연결을 설정하고 필요한 정보를 제공하는 바인딩 두 가지 통합이 포함됩니다.

.NET .NET Aspire은 두 가지 서비스 바인딩 유형을 지원합니다: 암시적서비스는 지정된 시작 프로필에 따라 다른 환경에서 앱의 동작을 정의하며 자동으로 생성되고, 를 사용하여 수동으로 생성되는 WithEndpoint서비스가 있습니다.

암시적 또는 명시적 바인딩을 만들 때 .NET.NET Aspire 지정된 포트에서 간단한 역방향 프록시를 시작하여 앱에서 서비스로의 요청에 대한 라우팅 및 부하 분산을 처리합니다. 프록시는 구성 또는 관리 문제가 필요하지 않은 .NET.NET Aspire 구현 세부 정보입니다.

엔드포인트의 작동 방식을 시각화하는 데 도움이 되도록 .NET.NET Aspire 시작 템플릿 내부 루프 네트워킹 다이어그램을 고려합니다.

프로필 실행

AddProject을(를) 호출하면, 앱 호스트가 속성/launchSettings를 찾아 엔드포인트의 기본 집합을 확인하기 위해json을(를) 사용합니다. 앱 호스트는 다음 규칙을 사용하여 특정 시작 프로필을 선택합니다.

launchProfileName을(를) 호출할 때 명시적으로 전달되는 AddProject 인수입니다.
DOTNET_LAUNCH_PROFILE 환경 변수입니다. 자세한 내용은 환경 변수를 참조하세요.
launchSettings에 정의된 첫 번째 시작 프로필입니다.json.

다음 launchSettings를 참조하십시오.json 파일:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "applicationUrl": "https://localhost:7239;http://localhost:5066",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

이 문서의 나머지 부분에서는 당신이 IDistributedApplicationBuilder API를 사용하여 builder 변수에 할당된 CreateBuilder()을 만들었다고 상상해 보세요.

var builder = DistributedApplication.CreateBuilder(args);

http 및 https 시작 프로필을 지정하려면 launchSettings에서 둘 다에 대한 값을 applicationUrl로 구성합니다.json 파일입니다. 이러한 URL은 이 프로젝트에 대한 엔드포인트를 만드는 데 사용됩니다. 이는 다음과 같습니다.

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066)
       .WithHttpsEndpoint(port: 7239);

중요하다

이 없는 경우, launchSettings.json(또는 시작 프로필)에는 기본적으로 바인딩이 설정되지 않습니다.

자세한 정보를 보려면 ,.NET,.NET Aspire 및 시작 프로필을 참조하세요.

Kestrel이 구성한 엔드포인트

.NET .NET Aspire Kestrel 엔드포인트 구성을 지원합니다. 예를 들어 HTTPS 체계와 포트 5271로 Kestrel 엔드포인트를 정의하는 프로젝트의 appsettingsjson 파일을 고려해 보세요.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:5271"
      }
    }
  }
}

위의 구성은 Https 엔드포인트를 지정합니다. Url 속성은 https://*:5271로 설정됩니다. 즉, 엔드포인트는 포트 5271에서 모든 인터페이스를 통해 수신 대기합니다. 자세한 내용은 ASP.NET Core Kestrel 웹 server대한 엔드포인트 구성을 참조하세요.

Kestrel 엔드포인트가 구성된 경우, 프로젝트는 launchSettings에서 설정된 applicationUrl을 제거해야 합니다.json 파일입니다.

메모

applicationUrl가 launchSettings에 있는 경우,json 파일이 있고 Kestrel 엔드포인트가 구성되면, 앱 호스트가 예외를 발생시킵니다.

프로젝트 리소스를 추가할 때 launchSettings 대신 Kestrel 엔드포인트를 사용해야 함을 지정할 수 있는 오버로드가 있습니다.json 파일:

builder.AddProject<Projects.Networking_ApiService>(
    name: "apiservice",
    configure: static project =>
    {
        project.ExcludeLaunchProfile = true;
        project.ExcludeKestrelEndpoints = false;
    })
    .WithHttpsEndpoint();

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

포트 및 프록시

서비스 바인딩을 정의할 때, 호스트 포트는 항상 서비스 앞에 위치한 프록시에 할당됩니다. 이렇게 하면 서비스의 단일 또는 여러 복제본이 비슷하게 동작할 수 있습니다. 또한 WithReference API를 사용하는 모든 리소스 종속성은 환경 변수의 프록시 엔드포인트를 사용합니다.

AddProject, WithHttpEndpoint및 WithReplicas호출하는 다음 메서드 체인을 고려합니다.

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066)
       .WithReplicas(2);

위의 코드는 다음 네트워킹 다이어그램을 생성합니다.

위의 다이어그램은 다음을 보여 줍니다.

웹 브라우저를 앱의 진입점으로 사용합니다.
5066의 호스트 포트입니다.
웹 브라우저와 프런트 엔드 서비스 복제본 사이에 있는 프런트 엔드 프록시로, 포트 5066에서 수신 대기합니다.
임의로 할당된 포트 65001에서 대기 중인 frontend_0 프런트엔드 서비스 인스턴스입니다.
임의로 할당된 포트 65002에서 수신 대기하는 frontend_1 프런트 엔드 서비스 복제본입니다.

WithReplicas호출하지 않으면 프런트 엔드 서비스가 하나만 있습니다. 프록시는 여전히 포트 5066에서 수신 대기하지만 프런트 엔드 서비스는 임의 포트에서 수신 대기합니다.

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint(port: 5066);

두 개의 포트가 정의되어 있습니다.

5066의 호스트 포트입니다.
기본 서비스가 바인딩될 임의 프록시 포트입니다.

위의 다이어그램은 다음을 보여 줍니다.

웹 브라우저를 앱의 진입점으로 사용합니다.
5066의 호스트 포트입니다.
웹 브라우저와 프런트 엔드 서비스 사이에 있는 프런트 엔드 프록시로, 포트 5066에서 수신 대기합니다.
65001의 임의 포트에서 수신 대기하는 프런트 엔드 서비스입니다.

기본 서비스는 ASPNETCORE_URLS를 통해 프로젝트 리소스에 이 포트를 전달합니다. 다른 리소스는 서비스 바인딩에 환경 변수를 지정하여 이 포트에 액세스합니다.

builder.AddNpmApp("frontend", "../NodeFrontend", "watch")
       .WithHttpEndpoint(port: 5067, env: "PORT");

이전 코드는 PORT 환경 변수에서 임의 포트를 사용할 수 있도록 합니다. 앱은 이 포트를 사용하여 프록시에서 들어오는 연결을 수신 대기합니다. 다음 다이어그램을 고려합니다.

위의 다이어그램은 다음을 보여 줍니다.

웹 브라우저를 앱의 진입점으로 사용합니다.
5067의 호스트 포트입니다.
웹 브라우저와 프런트 엔드 서비스 사이에 있는 프런트 엔드 프록시로, 포트 5067에서 수신 대기합니다.
환경 65001에서 수신 대기하는 프런트 엔드 서비스입니다.

팁

엔드포인트가 프록시되지 않도록 하려면 IsProxied 확장 메서드를 호출할 때 false 속성을 WithEndpoint로 설정합니다. 자세한 내용은 엔드포인트 확장:추가 고려 사항을 참조하세요.

호스트 포트 생략

호스트 포트를 생략하면 .NET.NET Aspire 호스트 및 서비스 포트 둘 다에 대해 임의의 포트를 생성합니다. 이는 포트 충돌을 방지하고 호스트 또는 서비스 포트에 대해 신경 쓰지 않으려는 경우에 유용합니다. 다음 코드를 고려합니다.

builder.AddProject<Projects.Networking_Frontend>("frontend")
       .WithHttpEndpoint();

이 시나리오에서는 다음 다이어그램과 같이 호스트 포트와 서비스 포트가 모두 임의입니다.

위의 다이어그램은 다음을 보여 줍니다.

웹 브라우저를 앱의 진입점으로 사용합니다.
65000의 임의 호스트 포트입니다.
웹 브라우저와 프런트 엔드 서비스 사이에 있는 프런트 엔드 프록시로, 포트 65000에서 수신 대기합니다.
65001의 임의 포트에서 수신 대기하는 프런트 엔드 서비스입니다.

컨테이너 포트

컨테이너 리소스를 추가하면 .NET.NET Aspire 컨테이너에 임의 포트를 자동으로 할당합니다. 컨테이너 포트를 지정하려면 원하는 포트를 사용하여 컨테이너 리소스를 구성합니다.

builder.AddContainer("frontend", "mcr.microsoft.com/dotnet/samples", "aspnetapp")
       .WithHttpEndpoint(port: 8000, targetPort: 8080);

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

frontend 이미지에서 mcr.microsoft.com/dotnet/samples:aspnetapp라는 컨테이너 리소스를 생성합니다.
호스트를 포트 8000에 바인딩하고 컨테이너의 포트 8080에 매핑하여 http 엔드포인트를 노출합니다.

다음 다이어그램을 고려합니다.

.NET Aspire 프런트엔드 애플리케이션 네트워킹 다이어그램은 docker 호스트와 함께 사용됩니다.

엔드포인트 확장 메서드

IResourceWithEndpoints 인터페이스를 구현하는 모든 리소스는 WithEndpoint 확장 메서드를 사용할 수 있습니다. 이 확장에는 여러 오버로드가 있으므로 스키마, 컨테이너 포트, 호스트 포트, 환경 변수 이름 및 엔드포인트의 프록시 여부를 지정할 수 있습니다.

엔드포인트를 설정할 때 대리자를 지정할 수 있는 오버로드도 제공됩니다. 이는 환경 또는 기타 요인에 따라 엔드포인트를 구성해야 하는 경우에 유용합니다. 다음 코드를 고려합니다.

builder.AddProject<Projects.Networking_ApiService>("apiService")
       .WithEndpoint(
            endpointName: "admin",
            callback: static endpoint =>
       {
           endpoint.Port = 17003;
           endpoint.UriScheme = "http";
           endpoint.Transport = "http";
       });

위의 코드는 엔드포인트를 구성하는 콜백 대리자를 제공합니다. 엔드포인트는 admin 이름이 지정되고 http 구성표 및 전송뿐만 아니라 17003 호스트 포트를 사용하도록 구성됩니다. 소비자는 이 엔드포인트를 이름으로 참조하며, 다음 AddHttpClient 호출을 고려합니다.

builder.Services.AddHttpClient<WeatherApiClient>(
    client => client.BaseAddress = new Uri("http://_admin.apiservice"));

Uri는 admin sentinel이 앞에 붙은 _ 엔드포인트 이름을 사용하여 생성됩니다. admin 세그먼트가 apiservice 서비스에 속하는 엔드포인트 이름임을 나타내는 규칙입니다. 자세한 내용은 .NET.NET Aspire 서비스 검색참조하세요.

추가 고려 사항

WithEndpoint 확장 메서드를 호출할 때 callback 오버로드는 원시 EndpointAnnotation노출하므로 소비자가 엔드포인트의 여러 측면을 사용자 지정할 수 있습니다.

AllocatedEndpoint 속성을 사용하면 서비스의 엔드포인트를 얻거나 설정할 수 있습니다. IsExternal 및 IsProxied 속성은 엔드포인트를 관리하고 노출하는 방법을 결정합니다. IsExternal 공개적으로 액세스할 수 있는지 여부를 결정하는 반면, IsProxied DCP가 이를 관리하여 내부 포트 차이 및 복제를 허용합니다.

팁

자체 프록시를 실행하는 외부 실행 파일을 호스팅하느라 DCP가 이미 포트를 차지하고 있어 포트 바인딩 문제가 발생한다면, IsProxied 속성을 false으로 설정해 보세요. 이렇게 하면 DCP에서 프록시를 관리할 수 없으므로 실행 파일이 포트를 성공적으로 바인딩할 수 있습니다.

Name 속성은 서비스를 식별하는 반면 Port 및 TargetPort 속성은 각각 원하는 포트와 수신 대기 포트를 지정합니다.

네트워크 통신의 경우 Protocol 속성은 TCP 및 UDP를 지원하며, 향후 더 많은 기능을 지원할 가능성이 있습니다. 또, Transport 속성은 전송 프로토콜(HTTP, HTTP2, HTTP3)을 나타냅니다. 마지막으로, 서비스가 URI 주소 지정 가능인 경우 UriScheme 속성은 서비스 URI를 생성하기 위한 URI 체계를 제공합니다.

자세한 내용은 EndpointAnnotation 속성사용 가능한 속성을 참조하세요.

엔드포인트 필터링

모든 .NET.NET Aspire 프로젝트 리소스 엔드포인트는 기본 추론 집합을 따릅니다. 일부 엔드포인트는 런타임에 ASPNETCORE_URLS에 포함되고, 일부는 HTTP/HTTPS_PORTS로 게시되며, 일부 구성은 Kestrel 구성에서 해석됩니다. 기본 동작에 관계없이 WithEndpointsInEnvironment 확장 메서드를 사용하여 환경 변수에 포함된 엔드포인트를 필터링할 수 있습니다.

builder.AddProject<Projects.Networking_ApiService>("apiservice")
    .WithHttpsEndpoint() // Adds a default "https" endpoint
    .WithHttpsEndpoint(port: 19227, name: "admin")
    .WithEndpointsInEnvironment(
        filter: static endpoint =>
        {
            return endpoint.Name is not "admin";
        });

위의 코드는 기본 HTTPS 엔드포인트와 포트 19227의 admin 엔드포인트를 추가합니다. 그러나 admin 엔드포인트는 환경 변수에서 제외됩니다. 내부용으로만 엔드포인트를 노출하려는 경우에 유용합니다.

다음을 통해 공유

.NET .NET Aspire 내부 루프 네트워킹 개요

내부 루프의 네트워킹

엔드포인트 작동 방식

프로필 실행

Kestrel이 구성한 엔드포인트

포트 및 프록시

호스트 포트 생략

컨테이너 포트

엔드포인트 확장 메서드

추가 고려 사항

엔드포인트 필터링

추가 리소스