다음을 통해 공유


ASP.NET Core를 사용하는 gRPC 서비스

참고 항목

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 8 버전을 참조 하세요.

Warning

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조 하세요. 현재 릴리스는 이 문서의 .NET 8 버전을 참조 하세요.

Important

이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

현재 릴리스는 이 문서의 .NET 8 버전을 참조 하세요.

이 문서에서는 ASP.NET Core를 사용하여 gRPC 서비스를 시작하는 방법을 보여 줍니다.

필수 조건

ASP.NET Core에서 gRPC 서비스 시작

예제 코드 살펴보기 및 다운로드 (다운로드 방법). 다운로드 예제는 영역을 테스트하기 위한 기초적인 앱을 제공합니다.

gRPC 프로젝트를 만드는 방법에 대한 자세한 내용은 gRPC 서비스 시작을 참조하세요.

ASP.NET Core 앱에 gRPC 서비스 추가

gRPC를 사용하려면 Grpc.AspNetCore 패키지가 필요합니다.

gRPC 구성

Program.cs의 경우

  • AddGrpc 메서드를 통해 gRPC를 사용하도록 설정합니다.
  • MapGrpcService 메서드를 통해 라우팅 파이프라인에 각 gRPC 서비스를 추가합니다.
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

영어 이외의 언어로 번역된 코드 주석을 보려면 이 GitHub 토론 이슈에서 알려주세요.

ASP.NET Core 미들웨어와 기능은 라우팅 파이프라인을 공유하므로 추가 요청 처리기를 제공하도록 앱을 구성할 수 있습니다. MVC 컨트롤러와 같은 추가 요청 처리기는 구성된 gRPC 서비스와 병렬로 작동합니다.

서버 옵션

gRPC 서비스는 모든 기본 제공 ASP.NET Core 서버에서 호스트할 수 있습니다.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상을 필요합니다.

ASP.NET Core 앱에서 올바른 서버를 선택하는 방법에 대한 자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

Kestrel

Kestrel은 플랫폼 간 ASP.NET Core의 웹 서버입니다. Kestrel은 고성능과 높은 메모리 사용률에 초점을 맞추지만 포트 공유와 같은 HTTP.sys의 고급 기능 중 일부를 제공하지 않습니다.

Kestrel gRPC 엔드포인트:

  • HTTP/2가 필요합니다.
  • TLS(전송 계층 보안)로 보호해야 합니다.

HTTP/2

gRPC에는 HTTP/2가 필요합니다. ASP.NET Core용 gRPC는 HttpRequest.ProtocolHTTP/2인지 확인합니다.

Kestrel은 대부분의 운영 체제에서 HTTP/2를 지원합니다. Kestrel 엔드포인트는 기본적으로 HTTP/1.1 및 HTTP/2 연결을 지원하도록 구성됩니다.

TLS

gRPC에 사용되는 Kestrel 엔드포인트는 TLS로 보호해야 합니다. 개발에서는 ASP.NET Core 개발 인증서가 있을 경우 TLS로 보호된 엔드포인트가 https://localhost:5001에 자동으로 생성됩니다. 구성이 필요하지 않습니다. https 접두사는 Kestrel 엔드포인트가 TLS를 사용하는지 확인합니다.

프로덕션에서는 TLS를 명시적으로 구성해야 합니다. 다음 appsettings.json 예제에서는 TLS로 보호되는 HTTP/2 엔드포인트가 제공됩니다.

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

또는 Program.cs에서 Kestrel 엔드포인트를 구성할 수 있습니다.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Kestrel을 통해 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel HTTPS 엔드포인트 구성을 참조하세요.

프로토콜 협상

TLS는 통신 보호 이상의 용도로 사용됩니다. TLS ALPN(Application-Layer Protocol Negotiation) 핸드셰이크는 엔드포인트가 여러 프로토콜을 지원하는 경우 클라이언트와 서버 간의 연결 프로토콜을 협상하는 데 사용됩니다. 이 협상은 연결에서 HTTP/1.1 또는 HTTP/2를 사용할 것인지를 결정합니다.

TLS 없이 HTTP/2 엔드포인트를 구성한 경우 엔드포인트의 ListenOptions.ProtocolsHttpProtocols.Http2로 설정해야 합니다. 협상이 없기 때문에 여러 프로토콜이 있는 엔드포인트(예: HttpProtocols.Http1AndHttp2)는 TLS 없이 사용할 수 없습니다. 안전하지 않은 엔드포인트에 대한 모든 연결은 기본적으로 HTTP/1.1로 설정되며 gRPC 호출이 실패합니다.

Kestrel을 통해 HTTP/2 및 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel 엔드포인트 구성을 참조하세요.

참고 항목

macOS는 .NET 8 이전의 TLS에서 ASP.NET Core gRPC를 지원하지 않습니다. .NET 7 이하를 사용하는 경우 macOS에서 gRPC 서비스를 성공적으로 실행하려면 추가 구성이 필요합니다. 자세한 내용은 macOS에서 ASP.NET Core gRPC 앱을 시작할 수 없음을 참조하세요.

IIS

IIS(인터넷 정보 서비스)는 ASP.NET Core를 비롯한 웹앱을 호스팅하기 위한 유연하고 안전하며 관리하기 쉬운 웹 서버입니다. IIS를 사용하여 gRPC 서비스를 호스트하려면 .NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상이 필요합니다.

TLS 및 HTTP/2를 사용하도록 IIS를 구성해야 합니다. 자세한 내용은 IIS에서 HTTP/2와 ASP.NET Core 사용을 참조하세요.

HTTP.sys

HTTP.sys Windows에서만 실행되는 ASP.NET Core용 웹 서버입니다. .NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상은 HTTP.sys gRPC 서비스를 호스트하는 데 필요합니다.

TLS 및 HTTP/2를 사용하도록 HTTP.sys를 구성해야 합니다. 자세한 내용은 HTTP.sys 웹 서버 HTTP/2 지원을 참조하세요.

non-ASP.NET Core 프로젝트에서 gRPC 호스트

ASP.NET Core gRPC 서버는 일반적으로 gRPC 템플릿에서 만들어집니다. 템플릿에서 만든 프로젝트 파일은 SDK로 사용합니다 Microsoft.NET.SDK.Web .

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

SDK 값은 Microsoft.NET.SDK.Web ASP.NET Core 프레임워크에 대한 참조를 자동으로 추가합니다. 이 참조를 통해 앱은 서버를 호스트하는 데 필요한 ASP.NET Core 형식을 사용할 수 있습니다.

다음 프로젝트 파일 설정을 사용하여 non-ASP.NET Core 프로젝트에 gRPC 서버를 추가할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

이전 프로젝트 파일:

  • SDK로 사용하지 Microsoft.NET.SDK.Web 않습니다.
  • Microsoft.AspNetCore.App에 프레임워크 참조를 추가합니다.
    • 프레임워크 참조를 사용하면 Windows 서비스, WPF 앱 또는 WinForms 앱과 같은 non-ASP.NET Core 앱에서 ASP.NET Core API를 사용할 수 있습니다.
    • 이제 앱은 ASP.NET Core API를 사용하여 ASP.NET Core 서버를 시작할 수 있습니다.
  • gRPC 요구 사항을 추가합니다.
    • 에 대한 NuGet 패키지 참조입니다 Grpc.AspNetCore.
    • .proto 파일.

프레임워크 참조 사용에 Microsoft.AspNetCore.App 대한 자세한 내용은 ASP.NET Core 공유 프레임워크 사용을 참조 하세요.

ASP.NET Core API와 통합

gRPC 서비스는 DI(종속성 주입), 로깅 등의 ASP.NET Core 기능에 대한 모든 권한이 있습니다. 예를 들어 서비스 구현에서 생성자를 통해 DI 컨테이너의 로거 서비스를 확인할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

기본적으로 gRPC 서비스 구현은 수명(Singleton, 범위 지정 또는 임시)을 사용하는 다른 DI 서비스를 확인할 수 있습니다.

gRPC 메서드의 HttpContext 확인

gRPC API는 메서드, 호스트, 헤더, 트레일러 등의 일부 HTTP/2 메시지 데이터에 대한 액세스를 제공합니다. 각 gRPC 메서드에 전달된 ServerCallContext 인수를 통해 액세스할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext는 모든 ASP.NET API의 HttpContext에 대한 모든 권한을 제공하지 않습니다. GetHttpContext 확장 메서드는 ASP.NET API의 기본 HTTP/2 메시지를 나타내는 HttpContext에 대한 모든 권한을 제공합니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

추가 리소스

이 문서에서는 ASP.NET Core를 사용하여 gRPC 서비스를 시작하는 방법을 보여 줍니다.

필수 조건

ASP.NET Core에서 gRPC 서비스 시작

예제 코드 살펴보기 및 다운로드 (다운로드 방법). 다운로드 예제는 영역을 테스트하기 위한 기초적인 앱을 제공합니다.

gRPC 프로젝트를 만드는 방법에 대한 자세한 내용은 gRPC 서비스 시작을 참조하세요.

ASP.NET Core 앱에 gRPC 서비스 추가

gRPC를 사용하려면 Grpc.AspNetCore 패키지가 필요합니다.

gRPC 구성

Program.cs의 경우

  • AddGrpc 메서드를 통해 gRPC를 사용하도록 설정합니다.
  • MapGrpcService 메서드를 통해 라우팅 파이프라인에 각 gRPC 서비스를 추가합니다.
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

영어 이외의 언어로 번역된 코드 주석을 보려면 이 GitHub 토론 이슈에서 알려주세요.

ASP.NET Core 미들웨어와 기능은 라우팅 파이프라인을 공유하므로 추가 요청 처리기를 제공하도록 앱을 구성할 수 있습니다. MVC 컨트롤러와 같은 추가 요청 처리기는 구성된 gRPC 서비스와 병렬로 작동합니다.

서버 옵션

gRPC 서비스는 모든 기본 제공 ASP.NET Core 서버에서 호스트할 수 있습니다.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상을 필요합니다.

ASP.NET Core 앱에서 올바른 서버를 선택하는 방법에 대한 자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

Kestrel

Kestrel은 플랫폼 간 ASP.NET Core의 웹 서버입니다. Kestrel은 고성능과 높은 메모리 사용률에 초점을 맞추지만 포트 공유와 같은 HTTP.sys의 고급 기능 중 일부를 제공하지 않습니다.

Kestrel gRPC 엔드포인트:

  • HTTP/2가 필요합니다.
  • TLS(전송 계층 보안)로 보호해야 합니다.

HTTP/2

gRPC에는 HTTP/2가 필요합니다. ASP.NET Core용 gRPC는 HttpRequest.ProtocolHTTP/2인지 확인합니다.

Kestrel은 대부분의 운영 체제에서 HTTP/2를 지원합니다. Kestrel 엔드포인트는 기본적으로 HTTP/1.1 및 HTTP/2 연결을 지원하도록 구성됩니다.

TLS

gRPC에 사용되는 Kestrel 엔드포인트는 TLS로 보호해야 합니다. 개발에서는 ASP.NET Core 개발 인증서가 있을 경우 TLS로 보호된 엔드포인트가 https://localhost:5001에 자동으로 생성됩니다. 구성이 필요하지 않습니다. https 접두사는 Kestrel 엔드포인트가 TLS를 사용하는지 확인합니다.

프로덕션에서는 TLS를 명시적으로 구성해야 합니다. 다음 appsettings.json 예제에서는 TLS로 보호되는 HTTP/2 엔드포인트가 제공됩니다.

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

또는 Program.cs에서 Kestrel 엔드포인트를 구성할 수 있습니다.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Kestrel을 통해 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel HTTPS 엔드포인트 구성을 참조하세요.

프로토콜 협상

TLS는 통신 보호 이상의 용도로 사용됩니다. TLS ALPN(Application-Layer Protocol Negotiation) 핸드셰이크는 엔드포인트가 여러 프로토콜을 지원하는 경우 클라이언트와 서버 간의 연결 프로토콜을 협상하는 데 사용됩니다. 이 협상은 연결에서 HTTP/1.1 또는 HTTP/2를 사용할 것인지를 결정합니다.

TLS 없이 HTTP/2 엔드포인트를 구성한 경우 엔드포인트의 ListenOptions.ProtocolsHttpProtocols.Http2로 설정해야 합니다. 협상이 없기 때문에 여러 프로토콜이 있는 엔드포인트(예: HttpProtocols.Http1AndHttp2)는 TLS 없이 사용할 수 없습니다. 안전하지 않은 엔드포인트에 대한 모든 연결은 기본적으로 HTTP/1.1로 설정되며 gRPC 호출이 실패합니다.

Kestrel을 통해 HTTP/2 및 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel 엔드포인트 구성을 참조하세요.

참고 항목

macOS는 .NET 8 이전의 TLS에서 ASP.NET Core gRPC를 지원하지 않습니다. .NET 7 이하를 사용하는 경우 macOS에서 gRPC 서비스를 성공적으로 실행하려면 추가 구성이 필요합니다. 자세한 내용은 macOS에서 ASP.NET Core gRPC 앱을 시작할 수 없음을 참조하세요.

IIS

IIS(인터넷 정보 서비스)는 ASP.NET Core를 비롯한 웹앱을 호스팅하기 위한 유연하고 안전하며 관리하기 쉬운 웹 서버입니다. IIS를 사용하여 gRPC 서비스를 호스트하려면 .NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상이 필요합니다.

TLS 및 HTTP/2를 사용하도록 IIS를 구성해야 합니다. 자세한 내용은 IIS에서 HTTP/2와 ASP.NET Core 사용을 참조하세요.

HTTP.sys

HTTP.sys Windows에서만 실행되는 ASP.NET Core용 웹 서버입니다. .NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상은 HTTP.sys gRPC 서비스를 호스트하는 데 필요합니다.

TLS 및 HTTP/2를 사용하도록 HTTP.sys를 구성해야 합니다. 자세한 내용은 HTTP.sys 웹 서버 HTTP/2 지원을 참조하세요.

non-ASP.NET Core 프로젝트에서 gRPC 호스트

ASP.NET Core gRPC 서버는 일반적으로 gRPC 템플릿에서 만들어집니다. 템플릿에서 만든 프로젝트 파일은 SDK로 사용합니다 Microsoft.NET.SDK.Web .

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

SDK 값은 Microsoft.NET.SDK.Web ASP.NET Core 프레임워크에 대한 참조를 자동으로 추가합니다. 이 참조를 통해 앱은 서버를 호스트하는 데 필요한 ASP.NET Core 형식을 사용할 수 있습니다.

다음 프로젝트 파일 설정을 사용하여 non-ASP.NET Core 프로젝트에 gRPC 서버를 추가할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

이전 프로젝트 파일:

  • SDK로 사용하지 Microsoft.NET.SDK.Web 않습니다.
  • Microsoft.AspNetCore.App에 프레임워크 참조를 추가합니다.
    • 프레임워크 참조를 사용하면 Windows 서비스, WPF 앱 또는 WinForms 앱과 같은 non-ASP.NET Core 앱에서 ASP.NET Core API를 사용할 수 있습니다.
    • 이제 앱은 ASP.NET Core API를 사용하여 ASP.NET Core 서버를 시작할 수 있습니다.
  • gRPC 요구 사항을 추가합니다.
    • 에 대한 NuGet 패키지 참조입니다 Grpc.AspNetCore.
    • .proto 파일.

프레임워크 참조 사용에 Microsoft.AspNetCore.App 대한 자세한 내용은 ASP.NET Core 공유 프레임워크 사용을 참조 하세요.

ASP.NET Core API와 통합

gRPC 서비스는 DI(종속성 주입), 로깅 등의 ASP.NET Core 기능에 대한 모든 권한이 있습니다. 예를 들어 서비스 구현에서 생성자를 통해 DI 컨테이너의 로거 서비스를 확인할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

기본적으로 gRPC 서비스 구현은 수명(Singleton, 범위 지정 또는 임시)을 사용하는 다른 DI 서비스를 확인할 수 있습니다.

gRPC 메서드의 HttpContext 확인

gRPC API는 메서드, 호스트, 헤더, 트레일러 등의 일부 HTTP/2 메시지 데이터에 대한 액세스를 제공합니다. 각 gRPC 메서드에 전달된 ServerCallContext 인수를 통해 액세스할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext는 모든 ASP.NET API의 HttpContext에 대한 모든 권한을 제공하지 않습니다. GetHttpContext 확장 메서드는 ASP.NET API의 기본 HTTP/2 메시지를 나타내는 HttpContext에 대한 모든 권한을 제공합니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

추가 리소스

이 문서에서는 ASP.NET Core를 사용하여 gRPC 서비스를 시작하는 방법을 보여 줍니다.

필수 조건

ASP.NET Core에서 gRPC 서비스 시작

예제 코드 살펴보기 및 다운로드 (다운로드 방법). 다운로드 예제는 영역을 테스트하기 위한 기초적인 앱을 제공합니다.

gRPC 프로젝트를 만드는 방법에 대한 자세한 내용은 gRPC 서비스 시작을 참조하세요.

ASP.NET Core 앱에 gRPC 서비스 추가

gRPC를 사용하려면 Grpc.AspNetCore 패키지가 필요합니다.

gRPC 구성

Program.cs의 경우

  • AddGrpc 메서드를 통해 gRPC를 사용하도록 설정합니다.
  • MapGrpcService 메서드를 통해 라우팅 파이프라인에 각 gRPC 서비스를 추가합니다.
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

영어 이외의 언어로 번역된 코드 주석을 보려면 이 GitHub 토론 이슈에서 알려주세요.

ASP.NET Core 미들웨어와 기능은 라우팅 파이프라인을 공유하므로 추가 요청 처리기를 제공하도록 앱을 구성할 수 있습니다. MVC 컨트롤러와 같은 추가 요청 처리기는 구성된 gRPC 서비스와 병렬로 작동합니다.

서버 옵션

gRPC 서비스는 모든 기본 제공 ASP.NET Core 서버에서 호스트할 수 있습니다.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상을 필요합니다.

ASP.NET Core 앱에서 올바른 서버를 선택하는 방법에 대한 자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

Kestrel

Kestrel은 플랫폼 간 ASP.NET Core의 웹 서버입니다. Kestrel은 고성능과 높은 메모리 사용률에 초점을 맞추지만 포트 공유와 같은 HTTP.sys의 고급 기능 중 일부를 제공하지 않습니다.

Kestrel gRPC 엔드포인트:

  • HTTP/2가 필요합니다.
  • TLS(전송 계층 보안)로 보호해야 합니다.

HTTP/2

gRPC에는 HTTP/2가 필요합니다. ASP.NET Core용 gRPC는 HttpRequest.ProtocolHTTP/2인지 확인합니다.

Kestrel은 대부분의 운영 체제에서 HTTP/2를 지원합니다. Kestrel 엔드포인트는 기본적으로 HTTP/1.1 및 HTTP/2 연결을 지원하도록 구성됩니다.

TLS

gRPC에 사용되는 Kestrel 엔드포인트는 TLS로 보호해야 합니다. 개발에서는 ASP.NET Core 개발 인증서가 있을 경우 TLS로 보호된 엔드포인트가 https://localhost:5001에 자동으로 생성됩니다. 구성이 필요하지 않습니다. https 접두사는 Kestrel 엔드포인트가 TLS를 사용하는지 확인합니다.

프로덕션에서는 TLS를 명시적으로 구성해야 합니다. 다음 appsettings.json 예제에서는 TLS로 보호되는 HTTP/2 엔드포인트가 제공됩니다.

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

또는 Program.cs에서 Kestrel 엔드포인트를 구성할 수 있습니다.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Kestrel을 통해 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel HTTPS 엔드포인트 구성을 참조하세요.

프로토콜 협상

TLS는 통신 보호 이상의 용도로 사용됩니다. TLS ALPN(Application-Layer Protocol Negotiation) 핸드셰이크는 엔드포인트가 여러 프로토콜을 지원하는 경우 클라이언트와 서버 간의 연결 프로토콜을 협상하는 데 사용됩니다. 이 협상은 연결에서 HTTP/1.1 또는 HTTP/2를 사용할 것인지를 결정합니다.

TLS 없이 HTTP/2 엔드포인트를 구성한 경우 엔드포인트의 ListenOptions.ProtocolsHttpProtocols.Http2로 설정해야 합니다. 협상이 없기 때문에 여러 프로토콜이 있는 엔드포인트(예: HttpProtocols.Http1AndHttp2)는 TLS 없이 사용할 수 없습니다. 안전하지 않은 엔드포인트에 대한 모든 연결은 기본적으로 HTTP/1.1로 설정되며 gRPC 호출이 실패합니다.

Kestrel을 통해 HTTP/2 및 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel 엔드포인트 구성을 참조하세요.

참고 항목

macOS는 .NET 8 이전의 TLS에서 ASP.NET Core gRPC를 지원하지 않습니다. .NET 7 이하를 사용하는 경우 macOS에서 gRPC 서비스를 성공적으로 실행하려면 추가 구성이 필요합니다. 자세한 내용은 macOS에서 ASP.NET Core gRPC 앱을 시작할 수 없음을 참조하세요.

IIS

IIS(인터넷 정보 서비스)는 ASP.NET Core를 비롯한 웹앱을 호스팅하기 위한 유연하고 안전하며 관리하기 쉬운 웹 서버입니다. IIS를 사용하여 gRPC 서비스를 호스트하려면 .NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상이 필요합니다.

TLS 및 HTTP/2를 사용하도록 IIS를 구성해야 합니다. 자세한 내용은 IIS에서 HTTP/2와 ASP.NET Core 사용을 참조하세요.

HTTP.sys

HTTP.sys Windows에서만 실행되는 ASP.NET Core용 웹 서버입니다. .NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상은 HTTP.sys gRPC 서비스를 호스트하는 데 필요합니다.

TLS 및 HTTP/2를 사용하도록 HTTP.sys를 구성해야 합니다. 자세한 내용은 HTTP.sys 웹 서버 HTTP/2 지원을 참조하세요.

non-ASP.NET Core 프로젝트에서 gRPC 호스트

ASP.NET Core gRPC 서버는 일반적으로 gRPC 템플릿에서 만들어집니다. 템플릿에서 만든 프로젝트 파일은 SDK로 사용합니다 Microsoft.NET.SDK.Web .

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

SDK 값은 Microsoft.NET.SDK.Web ASP.NET Core 프레임워크에 대한 참조를 자동으로 추가합니다. 이 참조를 통해 앱은 서버를 호스트하는 데 필요한 ASP.NET Core 형식을 사용할 수 있습니다.

다음 프로젝트 파일 설정을 사용하여 non-ASP.NET Core 프로젝트에 gRPC 서버를 추가할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

이전 프로젝트 파일:

  • SDK로 사용하지 Microsoft.NET.SDK.Web 않습니다.
  • Microsoft.AspNetCore.App에 프레임워크 참조를 추가합니다.
    • 프레임워크 참조를 사용하면 Windows 서비스, WPF 앱 또는 WinForms 앱과 같은 non-ASP.NET Core 앱에서 ASP.NET Core API를 사용할 수 있습니다.
    • 이제 앱은 ASP.NET Core API를 사용하여 ASP.NET Core 서버를 시작할 수 있습니다.
  • gRPC 요구 사항을 추가합니다.
    • 에 대한 NuGet 패키지 참조입니다 Grpc.AspNetCore.
    • .proto 파일.

프레임워크 참조 사용에 Microsoft.AspNetCore.App 대한 자세한 내용은 ASP.NET Core 공유 프레임워크 사용을 참조 하세요.

ASP.NET Core API와 통합

gRPC 서비스는 DI(종속성 주입), 로깅 등의 ASP.NET Core 기능에 대한 모든 권한이 있습니다. 예를 들어 서비스 구현에서 생성자를 통해 DI 컨테이너의 로거 서비스를 확인할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

기본적으로 gRPC 서비스 구현은 수명(Singleton, 범위 지정 또는 임시)을 사용하는 다른 DI 서비스를 확인할 수 있습니다.

gRPC 메서드의 HttpContext 확인

gRPC API는 메서드, 호스트, 헤더, 트레일러 등의 일부 HTTP/2 메시지 데이터에 대한 액세스를 제공합니다. 각 gRPC 메서드에 전달된 ServerCallContext 인수를 통해 액세스할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext는 모든 ASP.NET API의 HttpContext에 대한 모든 권한을 제공하지 않습니다. GetHttpContext 확장 메서드는 ASP.NET API의 기본 HTTP/2 메시지를 나타내는 HttpContext에 대한 모든 권한을 제공합니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

추가 리소스

이 문서에서는 ASP.NET Core를 사용하여 gRPC 서비스를 시작하는 방법을 보여 줍니다.

필수 조건

ASP.NET Core에서 gRPC 서비스 시작

예제 코드 살펴보기 및 다운로드 (다운로드 방법). 다운로드 예제는 영역을 테스트하기 위한 기초적인 앱을 제공합니다.

gRPC 프로젝트를 만드는 방법에 대한 자세한 내용은 gRPC 서비스 시작을 참조하세요.

ASP.NET Core 앱에 gRPC 서비스 추가

gRPC를 사용하려면 Grpc.AspNetCore 패키지가 필요합니다.

gRPC 구성

Startup.cs의 경우

  • AddGrpc 메서드를 통해 gRPC를 사용하도록 설정합니다.
  • MapGrpcService 메서드를 통해 라우팅 파이프라인에 각 gRPC 서비스를 추가합니다.
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

영어 이외의 언어로 번역된 코드 주석을 보려면 이 GitHub 토론 이슈에서 알려주세요.

ASP.NET Core 미들웨어와 기능은 라우팅 파이프라인을 공유하므로 추가 요청 처리기를 제공하도록 앱을 구성할 수 있습니다. MVC 컨트롤러와 같은 추가 요청 처리기는 구성된 gRPC 서비스와 병렬로 작동합니다.

서버 옵션

gRPC 서비스는 모든 기본 제공 ASP.NET Core 서버에서 호스트할 수 있습니다.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상을 필요합니다.

ASP.NET Core 앱에서 올바른 서버를 선택하는 방법에 대한 자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

Kestrel

Kestrel은 플랫폼 간 ASP.NET Core의 웹 서버입니다. Kestrel은 고성능과 높은 메모리 사용률에 초점을 맞추지만 포트 공유와 같은 HTTP.sys의 고급 기능 중 일부를 제공하지 않습니다.

Kestrel gRPC 엔드포인트:

  • HTTP/2가 필요합니다.
  • TLS(전송 계층 보안)로 보호해야 합니다.

HTTP/2

gRPC에는 HTTP/2가 필요합니다. ASP.NET Core용 gRPC는 HttpRequest.ProtocolHTTP/2인지 확인합니다.

Kestrel은 대부분의 운영 체제에서 HTTP/2를 지원합니다. Kestrel 엔드포인트는 기본적으로 HTTP/1.1 및 HTTP/2 연결을 지원하도록 구성됩니다.

TLS

gRPC에 사용되는 Kestrel 엔드포인트는 TLS로 보호해야 합니다. 개발에서는 ASP.NET Core 개발 인증서가 있을 경우 TLS로 보호된 엔드포인트가 https://localhost:5001에 자동으로 생성됩니다. 구성이 필요하지 않습니다. https 접두사는 Kestrel 엔드포인트가 TLS를 사용하는지 확인합니다.

프로덕션에서는 TLS를 명시적으로 구성해야 합니다. 다음 appsettings.json 예제에서는 TLS로 보호되는 HTTP/2 엔드포인트가 제공됩니다.

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

또는 Program.cs에서 Kestrel 엔드포인트를 구성할 수 있습니다.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Kestrel을 통해 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel HTTPS 엔드포인트 구성을 참조하세요.

프로토콜 협상

TLS는 통신 보호 이상의 용도로 사용됩니다. TLS ALPN(Application-Layer Protocol Negotiation) 핸드셰이크는 엔드포인트가 여러 프로토콜을 지원하는 경우 클라이언트와 서버 간의 연결 프로토콜을 협상하는 데 사용됩니다. 이 협상은 연결에서 HTTP/1.1 또는 HTTP/2를 사용할 것인지를 결정합니다.

TLS 없이 HTTP/2 엔드포인트를 구성한 경우 엔드포인트의 ListenOptions.ProtocolsHttpProtocols.Http2로 설정해야 합니다. 협상이 없기 때문에 여러 프로토콜이 있는 엔드포인트(예: HttpProtocols.Http1AndHttp2)는 TLS 없이 사용할 수 없습니다. 안전하지 않은 엔드포인트에 대한 모든 연결은 기본적으로 HTTP/1.1로 설정되며 gRPC 호출이 실패합니다.

Kestrel을 통해 HTTP/2 및 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel 엔드포인트 구성을 참조하세요.

참고 항목

macOS는 .NET 8 이전의 TLS에서 ASP.NET Core gRPC를 지원하지 않습니다. .NET 7 이하를 사용하는 경우 macOS에서 gRPC 서비스를 성공적으로 실행하려면 추가 구성이 필요합니다. 자세한 내용은 macOS에서 ASP.NET Core gRPC 앱을 시작할 수 없음을 참조하세요.

IIS

IIS(인터넷 정보 서비스)는 ASP.NET Core를 비롯한 웹앱을 호스팅하기 위한 유연하고 안전하며 관리하기 쉬운 웹 서버입니다. IIS를 사용하여 gRPC 서비스를 호스트하려면 .NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상이 필요합니다.

TLS 및 HTTP/2를 사용하도록 IIS를 구성해야 합니다. 자세한 내용은 IIS에서 HTTP/2와 ASP.NET Core 사용을 참조하세요.

HTTP.sys

HTTP.sys Windows에서만 실행되는 ASP.NET Core용 웹 서버입니다. .NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상은 HTTP.sys gRPC 서비스를 호스트하는 데 필요합니다.

TLS 및 HTTP/2를 사용하도록 HTTP.sys를 구성해야 합니다. 자세한 내용은 HTTP.sys 웹 서버 HTTP/2 지원을 참조하세요.

non-ASP.NET Core 프로젝트에서 gRPC 호스트

ASP.NET Core gRPC 서버는 일반적으로 gRPC 템플릿에서 만들어집니다. 템플릿에서 만든 프로젝트 파일은 SDK로 사용합니다 Microsoft.NET.SDK.Web .

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

SDK 값은 Microsoft.NET.SDK.Web ASP.NET Core 프레임워크에 대한 참조를 자동으로 추가합니다. 이 참조를 통해 앱은 서버를 호스트하는 데 필요한 ASP.NET Core 형식을 사용할 수 있습니다.

다음 프로젝트 파일 설정을 사용하여 non-ASP.NET Core 프로젝트에 gRPC 서버를 추가할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

이전 프로젝트 파일:

  • SDK로 사용하지 Microsoft.NET.SDK.Web 않습니다.
  • Microsoft.AspNetCore.App에 프레임워크 참조를 추가합니다.
    • 프레임워크 참조를 사용하면 Windows 서비스, WPF 앱 또는 WinForms 앱과 같은 non-ASP.NET Core 앱에서 ASP.NET Core API를 사용할 수 있습니다.
    • 이제 앱은 ASP.NET Core API를 사용하여 ASP.NET Core 서버를 시작할 수 있습니다.
  • gRPC 요구 사항을 추가합니다.
    • 에 대한 NuGet 패키지 참조입니다 Grpc.AspNetCore.
    • .proto 파일.

프레임워크 참조 사용에 Microsoft.AspNetCore.App 대한 자세한 내용은 ASP.NET Core 공유 프레임워크 사용을 참조 하세요.

ASP.NET Core API와 통합

gRPC 서비스는 DI(종속성 주입), 로깅 등의 ASP.NET Core 기능에 대한 모든 권한이 있습니다. 예를 들어 서비스 구현에서 생성자를 통해 DI 컨테이너의 로거 서비스를 확인할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

기본적으로 gRPC 서비스 구현은 수명(Singleton, 범위 지정 또는 임시)을 사용하는 다른 DI 서비스를 확인할 수 있습니다.

gRPC 메서드의 HttpContext 확인

gRPC API는 메서드, 호스트, 헤더, 트레일러 등의 일부 HTTP/2 메시지 데이터에 대한 액세스를 제공합니다. 각 gRPC 메서드에 전달된 ServerCallContext 인수를 통해 액세스할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext는 모든 ASP.NET API의 HttpContext에 대한 모든 권한을 제공하지 않습니다. GetHttpContext 확장 메서드는 ASP.NET API의 기본 HTTP/2 메시지를 나타내는 HttpContext에 대한 모든 권한을 제공합니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

추가 리소스

이 문서에서는 ASP.NET Core를 사용하여 gRPC 서비스를 시작하는 방법을 보여 줍니다.

필수 조건

ASP.NET Core에서 gRPC 서비스 시작

예제 코드 살펴보기 및 다운로드 (다운로드 방법). 다운로드 예제는 영역을 테스트하기 위한 기초적인 앱을 제공합니다.

gRPC 프로젝트를 만드는 방법에 대한 자세한 내용은 gRPC 서비스 시작을 참조하세요.

ASP.NET Core 앱에 gRPC 서비스 추가

gRPC를 사용하려면 Grpc.AspNetCore 패키지가 필요합니다.

gRPC 구성

Startup.cs의 경우

  • AddGrpc 메서드를 통해 gRPC를 사용하도록 설정합니다.
  • MapGrpcService 메서드를 통해 라우팅 파이프라인에 각 gRPC 서비스를 추가합니다.
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

영어 이외의 언어로 번역된 코드 주석을 보려면 이 GitHub 토론 이슈에서 알려주세요.

ASP.NET Core 미들웨어와 기능은 라우팅 파이프라인을 공유하므로 추가 요청 처리기를 제공하도록 앱을 구성할 수 있습니다. MVC 컨트롤러와 같은 추가 요청 처리기는 구성된 gRPC 서비스와 병렬로 작동합니다.

서버 옵션

gRPC 서비스는 모든 기본 제공 ASP.NET Core 서버에서 호스트할 수 있습니다.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상을 필요합니다.

ASP.NET Core 앱에서 올바른 서버를 선택하는 방법에 대한 자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

Kestrel

Kestrel은 플랫폼 간 ASP.NET Core의 웹 서버입니다. Kestrel은 고성능과 높은 메모리 사용률에 초점을 맞추지만 포트 공유와 같은 HTTP.sys의 고급 기능 중 일부를 제공하지 않습니다.

Kestrel gRPC 엔드포인트:

  • HTTP/2가 필요합니다.
  • TLS(전송 계층 보안)로 보호해야 합니다.

HTTP/2

gRPC에는 HTTP/2가 필요합니다. ASP.NET Core용 gRPC는 HttpRequest.ProtocolHTTP/2인지 확인합니다.

Kestrel은 대부분의 운영 체제에서 HTTP/2를 지원합니다. Kestrel 엔드포인트는 기본적으로 HTTP/1.1 및 HTTP/2 연결을 지원하도록 구성됩니다.

TLS

gRPC에 사용되는 Kestrel 엔드포인트는 TLS로 보호해야 합니다. 개발에서는 ASP.NET Core 개발 인증서가 있을 경우 TLS로 보호된 엔드포인트가 https://localhost:5001에 자동으로 생성됩니다. 구성이 필요하지 않습니다. https 접두사는 Kestrel 엔드포인트가 TLS를 사용하는지 확인합니다.

프로덕션에서는 TLS를 명시적으로 구성해야 합니다. 다음 appsettings.json 예제에서는 TLS로 보호되는 HTTP/2 엔드포인트가 제공됩니다.

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

또는 Program.cs에서 Kestrel 엔드포인트를 구성할 수 있습니다.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Kestrel을 통해 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel HTTPS 엔드포인트 구성을 참조하세요.

프로토콜 협상

TLS는 통신 보호 이상의 용도로 사용됩니다. TLS ALPN(Application-Layer Protocol Negotiation) 핸드셰이크는 엔드포인트가 여러 프로토콜을 지원하는 경우 클라이언트와 서버 간의 연결 프로토콜을 협상하는 데 사용됩니다. 이 협상은 연결에서 HTTP/1.1 또는 HTTP/2를 사용할 것인지를 결정합니다.

TLS 없이 HTTP/2 엔드포인트를 구성한 경우 엔드포인트의 ListenOptions.ProtocolsHttpProtocols.Http2로 설정해야 합니다. 협상이 없기 때문에 여러 프로토콜이 있는 엔드포인트(예: HttpProtocols.Http1AndHttp2)는 TLS 없이 사용할 수 없습니다. 안전하지 않은 엔드포인트에 대한 모든 연결은 기본적으로 HTTP/1.1로 설정되며 gRPC 호출이 실패합니다.

Kestrel을 통해 HTTP/2 및 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel 엔드포인트 구성을 참조하세요.

참고 항목

macOS는 .NET 8 이전의 TLS에서 ASP.NET Core gRPC를 지원하지 않습니다. .NET 7 이하를 사용하는 경우 macOS에서 gRPC 서비스를 성공적으로 실행하려면 추가 구성이 필요합니다. 자세한 내용은 macOS에서 ASP.NET Core gRPC 앱을 시작할 수 없음을 참조하세요.

non-ASP.NET Core 프로젝트에서 gRPC 호스트

ASP.NET Core gRPC 서버는 일반적으로 gRPC 템플릿에서 만들어집니다. 템플릿에서 만든 프로젝트 파일은 SDK로 사용합니다 Microsoft.NET.SDK.Web .

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

SDK 값은 Microsoft.NET.SDK.Web ASP.NET Core 프레임워크에 대한 참조를 자동으로 추가합니다. 이 참조를 통해 앱은 서버를 호스트하는 데 필요한 ASP.NET Core 형식을 사용할 수 있습니다.

다음 프로젝트 파일 설정을 사용하여 non-ASP.NET Core 프로젝트에 gRPC 서버를 추가할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

이전 프로젝트 파일:

  • SDK로 사용하지 Microsoft.NET.SDK.Web 않습니다.
  • Microsoft.AspNetCore.App에 프레임워크 참조를 추가합니다.
    • 프레임워크 참조를 사용하면 Windows 서비스, WPF 앱 또는 WinForms 앱과 같은 non-ASP.NET Core 앱에서 ASP.NET Core API를 사용할 수 있습니다.
    • 이제 앱은 ASP.NET Core API를 사용하여 ASP.NET Core 서버를 시작할 수 있습니다.
  • gRPC 요구 사항을 추가합니다.
    • 에 대한 NuGet 패키지 참조입니다 Grpc.AspNetCore.
    • .proto 파일.

프레임워크 참조 사용에 Microsoft.AspNetCore.App 대한 자세한 내용은 ASP.NET Core 공유 프레임워크 사용을 참조 하세요.

ASP.NET Core API와 통합

gRPC 서비스는 DI(종속성 주입), 로깅 등의 ASP.NET Core 기능에 대한 모든 권한이 있습니다. 예를 들어 서비스 구현에서 생성자를 통해 DI 컨테이너의 로거 서비스를 확인할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

기본적으로 gRPC 서비스 구현은 수명(Singleton, 범위 지정 또는 임시)을 사용하는 다른 DI 서비스를 확인할 수 있습니다.

gRPC 메서드의 HttpContext 확인

gRPC API는 메서드, 호스트, 헤더, 트레일러 등의 일부 HTTP/2 메시지 데이터에 대한 액세스를 제공합니다. 각 gRPC 메서드에 전달된 ServerCallContext 인수를 통해 액세스할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext는 모든 ASP.NET API의 HttpContext에 대한 모든 권한을 제공하지 않습니다. GetHttpContext 확장 메서드는 ASP.NET API의 기본 HTTP/2 메시지를 나타내는 HttpContext에 대한 모든 권한을 제공합니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

추가 리소스

이 문서에서는 ASP.NET Core를 사용하여 gRPC 서비스를 시작하는 방법을 보여 줍니다.

필수 조건

ASP.NET Core에서 gRPC 서비스 시작

예제 코드 살펴보기 및 다운로드 (다운로드 방법). 다운로드 예제는 영역을 테스트하기 위한 기초적인 앱을 제공합니다.

gRPC 프로젝트를 만드는 방법에 대한 자세한 내용은 gRPC 서비스 시작을 참조하세요.

ASP.NET Core 앱에 gRPC 서비스 추가

gRPC를 사용하려면 Grpc.AspNetCore 패키지가 필요합니다.

gRPC 구성

Startup.cs의 경우

  • AddGrpc 메서드를 통해 gRPC를 사용하도록 설정합니다.
  • MapGrpcService 메서드를 통해 라우팅 파이프라인에 각 gRPC 서비스를 추가합니다.
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

영어 이외의 언어로 번역된 코드 주석을 보려면 이 GitHub 토론 이슈에서 알려주세요.

ASP.NET Core 미들웨어와 기능은 라우팅 파이프라인을 공유하므로 추가 요청 처리기를 제공하도록 앱을 구성할 수 있습니다. MVC 컨트롤러와 같은 추가 요청 처리기는 구성된 gRPC 서비스와 병렬로 작동합니다.

서버 옵션

gRPC 서비스는 모든 기본 제공 ASP.NET Core 서버에서 호스트할 수 있습니다.

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 및 Windows 11 빌드 22000 또는 Windows Server 2022 빌드 20348 이상을 필요합니다.

ASP.NET Core 앱에서 올바른 서버를 선택하는 방법에 대한 자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

Kestrel

Kestrel은 플랫폼 간 ASP.NET Core의 웹 서버입니다. Kestrel은 고성능과 높은 메모리 사용률에 초점을 맞추지만 포트 공유와 같은 HTTP.sys의 고급 기능 중 일부를 제공하지 않습니다.

Kestrel gRPC 엔드포인트:

  • HTTP/2가 필요합니다.
  • TLS(전송 계층 보안)로 보호해야 합니다.

HTTP/2

gRPC에는 HTTP/2가 필요합니다. ASP.NET Core용 gRPC는 HttpRequest.ProtocolHTTP/2인지 확인합니다.

Kestrel은 대부분의 운영 체제에서 HTTP/2를 지원합니다. Kestrel 엔드포인트는 기본적으로 HTTP/1.1 및 HTTP/2 연결을 지원하도록 구성됩니다.

TLS

gRPC에 사용되는 Kestrel 엔드포인트는 TLS로 보호해야 합니다. 개발에서는 ASP.NET Core 개발 인증서가 있을 경우 TLS로 보호된 엔드포인트가 https://localhost:5001에 자동으로 생성됩니다. 구성이 필요하지 않습니다. https 접두사는 Kestrel 엔드포인트가 TLS를 사용하는지 확인합니다.

프로덕션에서는 TLS를 명시적으로 구성해야 합니다. 다음 appsettings.json 예제에서는 TLS로 보호되는 HTTP/2 엔드포인트가 제공됩니다.

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

또는 Program.cs에서 Kestrel 엔드포인트를 구성할 수 있습니다.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Kestrel을 통해 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel HTTPS 엔드포인트 구성을 참조하세요.

프로토콜 협상

TLS는 통신 보호 이상의 용도로 사용됩니다. TLS ALPN(Application-Layer Protocol Negotiation) 핸드셰이크는 엔드포인트가 여러 프로토콜을 지원하는 경우 클라이언트와 서버 간의 연결 프로토콜을 협상하는 데 사용됩니다. 이 협상은 연결에서 HTTP/1.1 또는 HTTP/2를 사용할 것인지를 결정합니다.

TLS 없이 HTTP/2 엔드포인트를 구성한 경우 엔드포인트의 ListenOptions.ProtocolsHttpProtocols.Http2로 설정해야 합니다. 협상이 없기 때문에 여러 프로토콜이 있는 엔드포인트(예: HttpProtocols.Http1AndHttp2)는 TLS 없이 사용할 수 없습니다. 안전하지 않은 엔드포인트에 대한 모든 연결은 기본적으로 HTTP/1.1로 설정되며 gRPC 호출이 실패합니다.

Kestrel을 통해 HTTP/2 및 TLS를 사용하도록 설정하는 방법에 대한 자세한 내용은 Kestrel 엔드포인트 구성을 참조하세요.

참고 항목

macOS는 .NET 8 이전의 TLS에서 ASP.NET Core gRPC를 지원하지 않습니다. .NET 7 이하를 사용하는 경우 macOS에서 gRPC 서비스를 성공적으로 실행하려면 추가 구성이 필요합니다. 자세한 내용은 macOS에서 ASP.NET Core gRPC 앱을 시작할 수 없음을 참조하세요.

non-ASP.NET Core 프로젝트에서 gRPC 호스트

ASP.NET Core gRPC 서버는 일반적으로 gRPC 템플릿에서 만들어집니다. 템플릿에서 만든 프로젝트 파일은 SDK로 사용합니다 Microsoft.NET.SDK.Web .

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

SDK 값은 Microsoft.NET.SDK.Web ASP.NET Core 프레임워크에 대한 참조를 자동으로 추가합니다. 이 참조를 통해 앱은 서버를 호스트하는 데 필요한 ASP.NET Core 형식을 사용할 수 있습니다.

다음 프로젝트 파일 설정을 사용하여 non-ASP.NET Core 프로젝트에 gRPC 서버를 추가할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

이전 프로젝트 파일:

  • SDK로 사용하지 Microsoft.NET.SDK.Web 않습니다.
  • Microsoft.AspNetCore.App에 프레임워크 참조를 추가합니다.
    • 프레임워크 참조를 사용하면 Windows 서비스, WPF 앱 또는 WinForms 앱과 같은 non-ASP.NET Core 앱에서 ASP.NET Core API를 사용할 수 있습니다.
    • 이제 앱은 ASP.NET Core API를 사용하여 ASP.NET Core 서버를 시작할 수 있습니다.
  • gRPC 요구 사항을 추가합니다.
    • 에 대한 NuGet 패키지 참조입니다 Grpc.AspNetCore.
    • .proto 파일.

프레임워크 참조 사용에 Microsoft.AspNetCore.App 대한 자세한 내용은 ASP.NET Core 공유 프레임워크 사용을 참조 하세요.

ASP.NET Core API와 통합

gRPC 서비스는 DI(종속성 주입), 로깅 등의 ASP.NET Core 기능에 대한 모든 권한이 있습니다. 예를 들어 서비스 구현에서 생성자를 통해 DI 컨테이너의 로거 서비스를 확인할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

기본적으로 gRPC 서비스 구현은 수명(Singleton, 범위 지정 또는 임시)을 사용하는 다른 DI 서비스를 확인할 수 있습니다.

gRPC 메서드의 HttpContext 확인

gRPC API는 메서드, 호스트, 헤더, 트레일러 등의 일부 HTTP/2 메시지 데이터에 대한 액세스를 제공합니다. 각 gRPC 메서드에 전달된 ServerCallContext 인수를 통해 액세스할 수 있습니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext는 모든 ASP.NET API의 HttpContext에 대한 모든 권한을 제공하지 않습니다. GetHttpContext 확장 메서드는 ASP.NET API의 기본 HTTP/2 메시지를 나타내는 HttpContext에 대한 모든 권한을 제공합니다.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

추가 리소스