Udostępnij za pośrednictwem

Usługi gRPC na platformie ASP.NET Core

  • Artykuł

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu dla platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz artykuł w wersji .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję artykułu .NET 9.

W tym dokumencie pokazano, jak rozpocząć pracę z usługami gRPC przy użyciu ASP.NET Core.

Wymagania wstępne

Wprowadzenie do usługi gRPC na platformie ASP.NET Core

Wyświetl lub pobierz przykładowy kod (jak pobrać).

Aby uzyskać szczegółowe instrukcje dotyczące tworzenia projektu gRPC, zobacz Wprowadzenie do usług gRPC.

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Program.cs:

  • gRPC jest włączone za pomocą metody AddGrpc.
  • Każda usługa gRPC jest dodawana do potoku routingu za pomocą metody MapGrpcService.
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();

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

ASP.NET Core middleware i funkcje dzielą się potokiem routingu, dlatego można skonfigurować aplikację do obsługi dodatkowych procedur obsługi żądań. Dodatkowe programy obsługi żądań, takie jak kontrolery MVC, działają równolegle ze skonfigurowanymi usługami gRPC.

Opcje serwera

Usługi gRPC mogą być hostowane przez wszystkie wbudowane serwery ASP.NET Core.

  • Kestrel
  • Serwer testowy
  • IIS
  • HTTP.sys†

†Wymaga programu .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowszego.

Aby uzyskać więcej informacji na temat wybierania odpowiedniego serwera dla aplikacji ASP.NET Core, zobacz Implementacje serwera sieci Web w ASP.NET Core.

Kestrel

Kestrel to międzyplatformowy serwer internetowy dla platformy ASP.NET Core. Kestrel koncentruje się na wysokiej wydajności i wykorzystaniu pamięci, ale nie ma niektórych zaawansowanych funkcji w HTTP.sys, takich jak udostępnianie portów.

Kestrel Punkty końcowe gRPC:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core weryfikuje, czy HttpRequest.Protocol jest HTTP/2.

Kestrel obsługuje protokół HTTP/2 w większości nowoczesnych systemów operacyjnych. Kestrel Punkty końcowe są domyślnie skonfigurowane do obsługi połączeń HTTP/1.1 i HTTP/2.

TLS

Kestrel punkty końcowe używane na potrzeby gRPC powinny być zabezpieczone przy użyciu protokołu TLS. Podczas tworzenia punkt końcowy zabezpieczony protokołem TLS jest automatycznie tworzony pod adresem https://localhost:5001, gdy obecny jest certyfikat deweloperski ASP.NET Core. Nie jest wymagana żadna konfiguracja. Prefiks https sprawdza, Kestrel czy punkt końcowy używa protokołu TLS.

W środowisku produkcyjnym protokół TLS musi być jawnie skonfigurowany. W poniższym appsettings.json przykładzie podano punkt końcowy HTTP/2 zabezpieczony przy użyciu protokołu TLS:

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

Alternatywnie Kestrel punkty końcowe można skonfigurować w Program.cs:

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>");
    });
});

Aby uzyskać więcej informacji na temat włączania protokołu TLS z Kestrel, zobacz konfigurację punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany nie tylko do zabezpieczania komunikacji. Uzgadnianie negocjacji protokołu TLS w warstwie aplikacji (ALPN) służy do negocjowania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów. Ta negocjacje określają, czy połączenie korzysta z protokołu HTTP/1.1, czy HTTP/2.

Jeśli punkt końcowy HTTP/2 jest skonfigurowany bez protokołu TLS, ListenOptions.Protocols musi być ustawione na HttpProtocols.Http2wartość. Punkt końcowy z wieloma protokołami, na HttpProtocols.Http1AndHttp2 przykład, nie może być używany bez protokołu TLS, ponieważ nie ma negocjacji. Wszystkie połączenia z niezabezpieczonym punktem końcowym domyślnie używają protokołu HTTP/1.1, a wywołania gRPC kończą się niepowodzeniem.

Aby uzyskać więcej informacji na temat włączania protokołu HTTP/2 i protokołu TLS za pomocą Kestrel, zobacz Kestrel konfigurację punktu końcowego.

Uwaga

System macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS przed platformą .NET 8. Dodatkowa konfiguracja jest wymagana do pomyślnego uruchomienia usług gRPC w systemie macOS w przypadku korzystania z platformy .NET 7 lub starszej wersji. Aby uzyskać więcej informacji, zobacz Nie można uruchomić aplikacji gRPC platformy ASP.NET Core w systemie macOS.

IIS

Internet Information Services (IIS) to elastyczny, bezpieczny i zarządzany serwer sieci Web do hostowania aplikacji internetowych, w tym ASP.NET Core. Do hostowania usług gRPC przy użyciu usług IIS są wymagane programy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze.

Usługi IIS muszą być skonfigurowane do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz Use ASP.NET Core with HTTP/2 on IIS (Używanie ASP.NET Core z protokołem HTTP/2 w usługach IIS).

HTTP.sys

HTTP.sys jest serwerem sieci Web dla platformy ASP.NET Core, który działa tylko w systemie Windows. Platformy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze są wymagane do hostowania usług gRPC z HTTP.sys.

HTTP.sys należy skonfigurować do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz obsługę protokołu HTTP/2 przez serwer internetowy HTTP.sys.

Hostowanie usługi gRPC w projektach non-ASP.NET Core

Serwer gRPC platformy ASP.NET Core jest zwykle tworzony na podstawie szablonu gRPC. Plik projektu utworzony przez szablon używa Microsoft.NET.SDK.Web jako zestawu SDK.

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

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

</Project>

Microsoft.NET.SDK.Web Wartość zestawu SDK automatycznie dodaje odwołanie do platformy ASP.NET Core. Odwołanie umożliwia aplikacji używanie typów ASP.NET Core wymaganych do hostowania serwera.

Serwer gRPC można dodać do projektów non-ASP.NET Core przy użyciu następujących ustawień pliku projektu:

<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>

Poprzedni plik projektu:

  • Nie używa Microsoft.NET.SDK.Web jako zestawu SDK.
  • Dodaje odwołanie do frameworku do Microsoft.AspNetCore.App elementu.
    • Odwołanie do frameworka umożliwia aplikacjom spoza ASP.NET Core, takim jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms, korzystanie z interfejsów API ASP.NET Core.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące korzystania z usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji frameworka, zobacz Jak korzystać z udostępnionej platformy ASP.NET Core.

Integracja z interfejsami API platformy ASP.NET Core

Usługi gRPC mają pełny dostęp do funkcji ASP.NET Core, takich jak wstrzykiwanie zależności (DI) i logowanie . Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI.

Wstrzykiwanie konstruktora:

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;

    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }
}

Iniekcja konstruktora podstawowego (.NET 8 lub nowszy):

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi DI o dowolnym cyklu życia (Singleton, Scoped lub Transient).

Rozwiązywanie problemów z protokołem HttpContext w metodach gRPC

Interfejs API gRPC zapewnia dostęp do niektórych danych komunikatów HTTP/2, takich jak metoda, host, nagłówek i przyczepy. Dostęp odbywa się za pośrednictwem argumentu przekazanego ServerCallContext do każdej metody gRPC:

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

ServerCallContext nie zapewnia pełnego dostępu do HttpContext wszystkich interfejsów API ASP.NET. GetHttpContext Metoda rozszerzenia zapewnia pełny dostęp do reprezentującego HttpContext podstawowy komunikat HTTP/2 w interfejsach API ASP.NET:

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
        });
    }
}

Dodatkowe zasoby

W tym dokumencie pokazano, jak rozpocząć pracę z usługami gRPC przy użyciu ASP.NET Core.

Wymagania wstępne

Wprowadzenie do usługi gRPC na platformie ASP.NET Core

Wyświetl lub pobierz przykładowy kod (jak pobrać).

Aby uzyskać szczegółowe instrukcje dotyczące tworzenia projektu gRPC, zobacz Wprowadzenie do usług gRPC.

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Program.cs:

  • gRPC jest włączone metodą AddGrpc.
  • Każda usługa gRPC jest dodawana do potoku routingu przez metodę MapGrpcService.
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();

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

Oprogramowanie pośredniczące ASP.NET Core i jego funkcje współużytkują potok routingu, dlatego aplikację można skonfigurować do obsługi dodatkowych żądań. Dodatkowe programy obsługi żądań, takie jak kontrolery MVC, działają równolegle ze skonfigurowanymi usługami gRPC.

Opcje serwera

Usługi gRPC mogą być hostowane przez wszystkie wbudowane serwery ASP.NET Core.

  • Kestrel
  • TestServer
  • IIS
  • HTTP.sys†

†Wymaga programu .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowszego.

Aby uzyskać więcej informacji na temat wybierania odpowiedniego serwera dla aplikacji ASP.NET Core, zobacz Implementacje serwera sieci Web w ASP.NET Core.

Kestrel

Kestrel to międzyplatformowy serwer internetowy dla platformy ASP.NET Core. Kestrel koncentruje się na wysokiej wydajności i wykorzystaniu pamięci, ale nie ma niektórych zaawansowanych funkcji w HTTP.sys, takich jak udostępnianie portów.

Kestrel Punkty końcowe gRPC:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy HttpRequest.Protocol jest HTTP/2.

Kestrel obsługuje protokół HTTP/2 w większości nowoczesnych systemów operacyjnych. Kestrel Punkty końcowe są domyślnie skonfigurowane do obsługi połączeń HTTP/1.1 i HTTP/2.

TLS

Kestrel punkty końcowe używane na potrzeby gRPC powinny być zabezpieczone przy użyciu protokołu TLS. W trakcie tworzenia automatycznie tworzony jest punkt dostępowy zabezpieczony przy użyciu protokołu TLS w https://localhost:5001, w przypadku obecności certyfikatu deweloperskiego ASP.NET Core. Nie jest wymagana żadna konfiguracja. Prefiks https sprawdza, Kestrel czy punkt końcowy używa protokołu TLS.

W środowisku produkcyjnym protokół TLS musi być jawnie skonfigurowany. W poniższym appsettings.json przykładzie podano punkt końcowy HTTP/2 zabezpieczony przy użyciu protokołu TLS:

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

Alternatywnie, końcowe punkty Kestrel można skonfigurować w Program.cs:

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>");
    });
});

Aby uzyskać więcej informacji na temat włączania protokołu TLS za pomocą Kestrel, zobacz Kestrel Konfigurację punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany nie tylko do zabezpieczania komunikacji. Uzgadnianie negocjacji protokołu TLS w warstwie aplikacji (ALPN) służy do negocjowania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów. Ta negocjacje określają, czy połączenie korzysta z protokołu HTTP/1.1, czy HTTP/2.

Jeśli punkt końcowy HTTP/2 jest skonfigurowany bez protokołu TLS, ListenOptions.Protocols musi być ustawiony na HttpProtocols.Http2. Punkt końcowy z wieloma protokołami, na HttpProtocols.Http1AndHttp2 przykład, nie może być używany bez protokołu TLS, ponieważ nie ma negocjacji. Wszystkie połączenia z niezabezpieczonym punktem końcowym są domyślnie ustawiane na HTTP/1.1, a wywołania gRPC kończą się niepowodzeniem.

Aby uzyskać więcej informacji na temat włączania protokołu HTTP/2 i TLS z Kestrel, zobacz Kestrel konfigurację punktu końcowego.

Uwaga

System macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS przed platformą .NET 8. Dodatkowa konfiguracja jest wymagana do pomyślnego uruchomienia usług gRPC w systemie macOS w przypadku korzystania z platformy .NET 7 lub starszej wersji. Aby uzyskać więcej informacji, zobacz Nie można uruchomić aplikacji gRPC platformy ASP.NET Core w systemie macOS.

IIS

Internet Information Services (IIS) to elastyczny, bezpieczny i zarządzany serwer sieci Web do hostowania aplikacji internetowych, w tym ASP.NET Core. Do hostowania usług gRPC przy użyciu usług IIS są wymagane programy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze.

Usługi IIS muszą być skonfigurowane do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz Use ASP.NET Core with HTTP/2 on IIS (Używanie ASP.NET Core z protokołem HTTP/2 w usługach IIS).

HTTP.sys

HTTP.sys jest serwerem sieci Web dla platformy ASP.NET Core, który działa tylko w systemie Windows. Platformy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze są wymagane do hostowania usług gRPC z HTTP.sys.

HTTP.sys należy skonfigurować do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz HTTP.sys obsługę protokołu HTTP/2 serwera internetowego.

Hostowanie usługi gRPC w projektach non-ASP.NET Core

Serwer gRPC platformy ASP.NET Core jest zwykle tworzony na podstawie szablonu gRPC. Plik projektu utworzony przez szablon używa Microsoft.NET.SDK.Web jako SDK.

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

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

</Project>

Microsoft.NET.SDK.Web Wartość zestawu SDK automatycznie dodaje odwołanie do platformy ASP.NET Core. Odwołanie pozwala aplikacji na wykorzystanie typów ASP.NET Core wymaganych do hostowania serwera.

Serwer gRPC można dodać do projektów non-ASP.NET Core przy użyciu następujących ustawień pliku projektu:

<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>

Poprzedni plik projektu:

  • Nie używa Microsoft.NET.SDK.Web jako zestawu SDK.
  • Dodaje odwołanie do frameworka do Microsoft.AspNetCore.App.
    • Odwołanie do platformy umożliwia aplikacjom spoza ASP.NET Core, takim jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms, korzystanie z interfejsów API ASP.NET Core.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Microsoft.AspNetCore.AppKorzystanie z platformy udostępnionej ASP.NET Core.

Integracja z interfejsami API platformy ASP.NET Core

Usługi gRPC mają pełny dostęp do funkcji ASP.NET Core, takich jak wstrzykiwanie zależności (DI) i logowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozwiązywać inne usługi DI o dowolnym czasie życia (Singleton, Scoped lub Przejściowy).

Rozwiązywanie problemów z protokołem HttpContext w metodach gRPC

Interfejs API gRPC zapewnia dostęp do niektórych danych komunikatów HTTP/2, takich jak metoda, host, nagłówki i trailery. Dostęp odbywa się za pośrednictwem argumentu przekazanego ServerCallContext do każdej metody gRPC:

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

ServerCallContext nie zapewnia pełnego dostępu do HttpContext wszystkich interfejsów API ASP.NET. GetHttpContext Metoda rozszerzeń zapewnia pełny dostęp do obiektu reprezentującego podstawowy komunikat HTTP/2 w interfejsach API ASP.NET.

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
        });
    }
}

Dodatkowe zasoby

W tym dokumencie pokazano, jak rozpocząć pracę z usługami gRPC przy użyciu ASP.NET Core.

Wymagania wstępne

Wprowadzenie do usługi gRPC na platformie ASP.NET Core

Wyświetl lub pobierz przykładowy kod (jak pobrać).

Aby uzyskać szczegółowe instrukcje dotyczące tworzenia projektu gRPC, zobacz Wprowadzenie do usług gRPC.

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Program.cs:

  • gRPC jest włączona za pomocą metody AddGrpc.
  • Każda usługa gRPC jest dodawana do potoku routingu za pośrednictwem metody MapGrpcService.
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();

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

ASP.NET Core middleware i funkcje współdzielą potok routingu, dlatego aplikację można skonfigurować do obsługi dodatkowych żądań. Dodatkowe programy obsługi żądań, takie jak kontrolery MVC, działają równolegle ze skonfigurowanymi usługami gRPC.

Opcje serwera

Usługi gRPC mogą być hostowane przez wszystkie wbudowane serwery ASP.NET Core.

  • Kestrel
  • TestServer
  • IIS
  • HTTP.sys†

†Wymaga programu .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowszego.

Aby uzyskać więcej informacji na temat wybierania odpowiedniego serwera dla aplikacji ASP.NET Core, zobacz Implementacje serwera sieci Web w ASP.NET Core.

Kestrel

Kestrel to międzyplatformowy serwer internetowy dla platformy ASP.NET Core. Kestrel koncentruje się na wysokiej wydajności i wykorzystaniu pamięci, ale nie ma niektórych zaawansowanych funkcji w HTTP.sys, takich jak udostępnianie portów.

Kestrel Punkty końcowe gRPC:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy protokół HttpRequest.Protocol to HTTP/2.

Kestrel obsługuje protokół HTTP/2 w większości nowoczesnych systemów operacyjnych. Kestrel Punkty końcowe są domyślnie skonfigurowane do obsługi połączeń HTTP/1.1 i HTTP/2.

TLS

Kestrel punkty końcowe używane na potrzeby gRPC powinny być zabezpieczone przy użyciu protokołu TLS. Podczas opracowywania punkt końcowy zabezpieczony przy użyciu protokołu TLS jest tworzony automatycznie w https://localhost:5001 kiedy obecny jest certyfikat deweloperski ASP.NET Core. Nie jest wymagana żadna konfiguracja. Prefiks https sprawdza, Kestrel czy punkt końcowy używa protokołu TLS.

W środowisku produkcyjnym protokół TLS musi być jawnie skonfigurowany. W poniższym appsettings.json przykładzie podano punkt końcowy HTTP/2 zabezpieczony przy użyciu protokołu TLS:

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

Alternatywnie Kestrel punkty końcowe można skonfigurować w Program.cs:

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>");
    });
});

Aby uzyskać więcej informacji na temat włączania protokołu TLS za pomocą Kestrelprogramu , zobacz Kestrel Konfiguracja punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany nie tylko do zabezpieczania komunikacji. Uzgadnianie negocjacji protokołu TLS w warstwie aplikacji (ALPN) służy do negocjowania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów. Ta negocjacje określają, czy połączenie korzysta z protokołu HTTP/1.1, czy HTTP/2.

Jeśli punkt końcowy HTTP/2 jest skonfigurowany bez protokołu TLS, opcja ListenOptions.Protocols musi być ustawiona na HttpProtocols.Http2. Punkt końcowy z wieloma protokołami, na HttpProtocols.Http1AndHttp2 przykład, nie może być używany bez protokołu TLS, ponieważ nie ma negocjacji. Wszystkie połączenia z niezabezpieczonym punktem końcowym domyślnie używają HTTP/1.1, a wywołania gRPC kończą się niepowodzeniem.

Aby uzyskać więcej informacji na temat włączania protokołu HTTP/2 i TLS za pomocą Kestrel, sprawdź Kestrel konfigurację punktu końcowego.

Uwaga

System macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS przed platformą .NET 8. Dodatkowa konfiguracja jest wymagana do pomyślnego uruchomienia usług gRPC w systemie macOS w przypadku korzystania z platformy .NET 7 lub starszej wersji. Aby uzyskać więcej informacji, zobacz Nie można uruchomić aplikacji gRPC platformy ASP.NET Core w systemie macOS.

IIS

Internet Information Services (IIS) to elastyczny, bezpieczny i zarządzany serwer sieci Web do hostowania aplikacji internetowych, w tym ASP.NET Core. Do hostowania usług gRPC przy użyciu usług IIS są wymagane programy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze.

Usługi IIS muszą być skonfigurowane do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz Use ASP.NET Core with HTTP/2 on IIS (Używanie ASP.NET Core z protokołem HTTP/2 w usługach IIS).

HTTP.sys

HTTP.sys jest serwerem sieci Web dla platformy ASP.NET Core, który działa tylko w systemie Windows. Platformy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze są wymagane do hostowania usług gRPC z HTTP.sys.

HTTP.sys należy skonfigurować do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz obsługę protokołu HTTP/2 przez serwer internetowy HTTP.sys.

Hostowanie usługi gRPC w projektach non-ASP.NET Core

Serwer gRPC platformy ASP.NET Core jest zwykle tworzony na podstawie szablonu gRPC. Plik projektu utworzony przez szablon używa Microsoft.NET.SDK.Web jako SDK.

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

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

</Project>

Microsoft.NET.SDK.Web Wartość zestawu SDK automatycznie dodaje odwołanie do platformy ASP.NET Core. Odwołanie umożliwia aplikacji używanie typów ASP.NET Core wymaganych do hostowania serwera.

Serwer gRPC można dodać do projektów non-ASP.NET Core przy użyciu następujących ustawień pliku projektu:

<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>

Poprzedni plik projektu:

  • Nie używa Microsoft.NET.SDK.Web jako zestawu SDK.
  • Dodaje odwołanie do frameworka do Microsoft.AspNetCore.App.
    • pl-PL: Referencja frameworka umożliwia aplikacjom nieopartym na ASP.NET Core, takim jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms, korzystanie z interfejsów API ASP.NET Core.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

pl-PL: Aby uzyskać więcej informacji na temat korzystania z odwołania do platformy Microsoft.AspNetCore.App, zobacz Korzystanie z udostępnionej platformy ASP.NET Core.

Integracja z interfejsami API platformy ASP.NET Core

Usługi gRPC mają pełny dostęp do funkcji ASP.NET Core, takich jak iniekcja zależności (DI) i logowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi DI o dowolnym czasie życia (Singleton, Scoped lub Przejściowy).

Rozwiązywanie problemów z protokołem HttpContext w metodach gRPC

Interfejs API gRPC zapewnia dostęp do niektórych danych komunikatów HTTP/2, takich jak metoda, host, nagłówek i trailery. Dostęp odbywa się za pośrednictwem argumentu przekazanego ServerCallContext do każdej metody gRPC:

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

ServerCallContext nie zapewnia pełnego dostępu do HttpContext wszystkich interfejsów API ASP.NET. Metoda rozszerzenia GetHttpContext zapewnia pełny dostęp do HttpContext, który reprezentuje podstawowy komunikat HTTP/2 w interfejsach API ASP.NET.

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
        });
    }
}

Dodatkowe zasoby

W tym dokumencie pokazano, jak rozpocząć pracę z usługami gRPC przy użyciu ASP.NET Core.

Wymagania wstępne

Wprowadzenie do usługi gRPC na platformie ASP.NET Core

Wyświetl lub pobierz przykładowy kod (jak pobrać).

Aby uzyskać szczegółowe instrukcje dotyczące tworzenia projektu gRPC, zobacz Wprowadzenie do usług gRPC.

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Startup.cs:

  • gRPC jest włączona za pomocą metody AddGrpc.
  • Każda usługa gRPC jest dodawana do potoku routingu za pomocą metody MapGrpcService.
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>();
        });
    }
}

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

ASP.NET Core oprogramowanie pośredniczące i funkcje dzielą potok routingu, dlatego można skonfigurować aplikację do obsługi dodatkowych żądań. Dodatkowe programy obsługi żądań, takie jak kontrolery MVC, działają równolegle ze skonfigurowanymi usługami gRPC.

Opcje serwera

Usługi gRPC mogą być hostowane przez wszystkie wbudowane serwery ASP.NET Core.

  • Kestrel
  • TestServer
  • IIS
  • HTTP.sys†

†Wymaga programu .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowszego.

Aby uzyskać więcej informacji na temat wybierania odpowiedniego serwera dla aplikacji ASP.NET Core, zobacz Implementacje serwera sieci Web w ASP.NET Core.

Kestrel

Kestrel to międzyplatformowy serwer internetowy dla platformy ASP.NET Core. Kestrel koncentruje się na wysokiej wydajności i wykorzystaniu pamięci, ale nie ma niektórych zaawansowanych funkcji w HTTP.sys, takich jak udostępnianie portów.

Kestrel Punkty końcowe gRPC:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy protokół HttpRequest.Protocol to HTTP/2.

Kestrel obsługuje protokół HTTP/2 w większości nowoczesnych systemów operacyjnych. Kestrel Punkty końcowe są domyślnie skonfigurowane do obsługi połączeń HTTP/1.1 i HTTP/2.

TLS

Kestrel punkty końcowe używane na potrzeby gRPC powinny być zabezpieczone przy użyciu protokołu TLS. W trakcie rozwoju, gdy jest obecny certyfikat dewelopera ASP.NET Core, punkt końcowy zabezpieczony przy użyciu protokołu TLS jest automatycznie tworzony pod https://localhost:5001. Nie jest wymagana żadna konfiguracja. Prefiks https sprawdza, Kestrel czy punkt końcowy używa protokołu TLS.

W środowisku produkcyjnym protokół TLS musi być jawnie skonfigurowany. W poniższym appsettings.json przykładzie podano punkt końcowy HTTP/2 zabezpieczony przy użyciu protokołu TLS:

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

Alternatywnie, punkty końcowe Kestrel można skonfigurować w programie Program.cs.

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>();
        });

Aby uzyskać więcej informacji na temat włączania protokołu TLS za pomocą Kestrel, zobacz Kestrel konfigurację punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do czegoś więcej niż tylko do zabezpieczania komunikacji. Negocjacja Protokołu Warstwy Aplikacji (ALPN) w ramach TLS służy do uzgadniania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów. Ta negocjacje określają, czy połączenie korzysta z protokołu HTTP/1.1, czy HTTP/2.

Jeśli punkt końcowy HTTP/2 jest skonfigurowany bez protokołu TLS, opcja ListenOptions.Protocols punktu końcowego musi być ustawiona na HttpProtocols.Http2. Punkt końcowy z wieloma protokołami, na HttpProtocols.Http1AndHttp2 przykład, nie może być używany bez protokołu TLS, ponieważ nie ma negocjacji. Wszystkie połączenia z niezabezpieczonym punktem końcowym są domyślnie ustawione na HTTP/1.1, a wywołania gRPC kończą się niepowodzeniem.

Aby uzyskać więcej informacji na temat włączania protokołu HTTP/2 i TLS za pomocą Kestrel, zobacz konfigurację punktu końcowego Kestrel.

Uwaga

System macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS przed platformą .NET 8. Dodatkowa konfiguracja jest wymagana do pomyślnego uruchomienia usług gRPC w systemie macOS w przypadku korzystania z platformy .NET 7 lub starszej wersji. Aby uzyskać więcej informacji, zobacz Nie można uruchomić aplikacji gRPC platformy ASP.NET Core w systemie macOS.

IIS

Internet Information Services (IIS) to elastyczny, bezpieczny i zarządzany serwer sieci Web do hostowania aplikacji internetowych, w tym ASP.NET Core. Do hostowania usług gRPC przy użyciu usług IIS są wymagane programy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze.

Usługi IIS muszą być skonfigurowane do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz Use ASP.NET Core with HTTP/2 on IIS (Używanie ASP.NET Core z protokołem HTTP/2 w usługach IIS).

HTTP.sys

HTTP.sys jest serwerem sieci Web dla platformy ASP.NET Core, który działa tylko w systemie Windows. Platformy .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowsze są wymagane do hostowania usług gRPC z HTTP.sys.

HTTP.sys należy skonfigurować do używania protokołów TLS i HTTP/2. Aby uzyskać więcej informacji, zobacz obsługę HTTP/2 serwera WWW HTTP.sys.

Hostowanie usługi gRPC w projektach non-ASP.NET Core

Serwer gRPC platformy ASP.NET Core jest zwykle tworzony na podstawie szablonu gRPC. Plik projektu utworzony przez szablon używa Microsoft.NET.SDK.Web jako SDK.

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

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

</Project>

Microsoft.NET.SDK.Web Wartość zestawu SDK automatycznie dodaje odwołanie do platformy ASP.NET Core. Odwołanie pozwala aplikacji na używanie typów ASP.NET Core wymaganych do hostowania serwera.

Serwer gRPC można dodać do projektów non-ASP.NET Core przy użyciu następujących ustawień pliku projektu:

<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>

Poprzedni plik projektu:

  • Nie używa Microsoft.NET.SDK.Web jako zestawu SDK.
  • Dodaje odwołanie do frameworku Microsoft.AspNetCore.App.
    • Odwołanie do platformy umożliwia aplikacjom non-ASP.NET Core, takim jak usługi systemu Windows, aplikacje WPF czy WinForms, korzystanie z interfejsów API ASP.NET Core.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z odniesienia do platformy, zobacz "Korzystanie z platformy współdzielonej ASP.NET Core" .

Integracja z interfejsami API platformy ASP.NET Core

Usługi gRPC mają pełny dostęp do funkcji ASP.NET Core, takich jak wstrzykiwanie zależności (DI) i logowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi DI o dowolnym czasie życia (Singleton, Scoped lub Przejściowy).

Rozwiązywanie problemów z protokołem HttpContext w metodach gRPC

Interfejs API gRPC zapewnia dostęp do niektórych danych komunikatów HTTP/2, takich jak metoda, host, nagłówki i trailery. Dostęp odbywa się za pośrednictwem argumentu przekazanego ServerCallContext do każdej metody gRPC:

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

ServerCallContext nie zapewnia pełnego dostępu do HttpContext wszystkich interfejsów API ASP.NET. Metoda rozszerzenia GetHttpContext zapewnia pełny dostęp do HttpContext reprezentującego podstawowy komunikat HTTP/2 w interfejsach API ASP.NET.

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
        });
    }
}

Dodatkowe zasoby

W tym dokumencie pokazano, jak rozpocząć pracę z usługami gRPC przy użyciu ASP.NET Core.

Wymagania wstępne

Wprowadzenie do usługi gRPC na platformie ASP.NET Core

Wyświetl lub pobierz przykładowy kod (jak pobrać).

Aby uzyskać szczegółowe instrukcje dotyczące tworzenia projektu gRPC, zobacz Wprowadzenie do usług gRPC.

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Startup.cs:

  • gRPC jest włączony za pomocą metody AddGrpc.
  • Każda usługa gRPC jest dodawana do potoku routingu za pośrednictwem metody MapGrpcService.
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>();
        });
    }
}

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

ASP.NET Core middleware i funkcje współużytkują potok routingu, dlatego aplikację można skonfigurować do obsługi dodatkowych obsług żądań. Dodatkowe programy obsługi żądań, takie jak kontrolery MVC, działają równolegle ze skonfigurowanymi usługami gRPC.

Opcje serwera

Usługi gRPC mogą być hostowane przez wszystkie wbudowane serwery ASP.NET Core.

  • Kestrel
  • SerwerTestowy
  • IIS
  • HTTP.sys†

†Wymaga programu .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowszego.

Aby uzyskać więcej informacji na temat wybierania odpowiedniego serwera dla aplikacji ASP.NET Core, zobacz Implementacje serwera sieci Web w ASP.NET Core.

Kestrel

Kestrel to międzyplatformowy serwer internetowy dla platformy ASP.NET Core. Kestrel koncentruje się na wysokiej wydajności i wykorzystaniu pamięci, ale nie ma niektórych zaawansowanych funkcji w HTTP.sys, takich jak udostępnianie portów.

Kestrel Punkty końcowe gRPC:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy HttpRequest.Protocol jest równy HTTP/2.

Kestrel obsługuje protokół HTTP/2 w większości nowoczesnych systemów operacyjnych. Kestrel Punkty końcowe są domyślnie skonfigurowane do obsługi połączeń HTTP/1.1 i HTTP/2.

TLS

Kestrel punkty końcowe używane na potrzeby gRPC powinny być zabezpieczone przy użyciu protokołu TLS. W trakcie tworzenia punkt końcowy zabezpieczony protokołem TLS jest automatycznie tworzony w https://localhost:5001, gdy obecny jest certyfikat deweloperski ASP.NET Core. Nie jest wymagana żadna konfiguracja. Prefiks https sprawdza, Kestrel czy punkt końcowy używa protokołu TLS.

W środowisku produkcyjnym protokół TLS musi być jawnie skonfigurowany. W poniższym appsettings.json przykładzie podano punkt końcowy HTTP/2 zabezpieczony przy użyciu protokołu TLS:

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

Alternatywnie Kestrel punkty końcowe można skonfigurować w Program.cs:

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>();
        });

Aby uzyskać więcej informacji na temat włączania protokołu TLS za pomocą Kestrel, zapoznaj się z KestrelKonfiguracją punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do więcej celów niż tylko zabezpieczanie komunikacji. Uzgadnianie negocjacji protokołu TLS w warstwie aplikacji (ALPN) służy do negocjowania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów. Ta negocjacje określają, czy połączenie korzysta z protokołu HTTP/1.1, czy HTTP/2.

Jeśli punkt końcowy HTTP/2 jest skonfigurowany bez protokołu TLS, ListenOptions.Protocols musi być ustawiony na HttpProtocols.Http2. Punkt końcowy z wieloma protokołami, na HttpProtocols.Http1AndHttp2 przykład, nie może być używany bez protokołu TLS, ponieważ nie ma negocjacji. Wszystkie połączenia z niezabezpieczonym punktem końcowym domyślnie używają protokołu HTTP/1.1, a wywołania gRPC kończą się niepowodzeniem.

Aby uzyskać więcej informacji na temat włączania protokołu HTTP/2 i TLS za pomocą Kestrel, zobacz konfigurację punktu końcowego Kestrel.

Uwaga

System macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS przed platformą .NET 8. Dodatkowa konfiguracja jest wymagana do pomyślnego uruchomienia usług gRPC w systemie macOS w przypadku korzystania z platformy .NET 7 lub starszej wersji. Aby uzyskać więcej informacji, zobacz Nie można uruchomić aplikacji gRPC platformy ASP.NET Core w systemie macOS.

Hostowanie usługi gRPC w projektach non-ASP.NET Core

Serwer gRPC platformy ASP.NET Core jest zwykle tworzony na podstawie szablonu gRPC. Plik projektu utworzony przez szablon używa Microsoft.NET.SDK.Web jako SDK.

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

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

</Project>

Microsoft.NET.SDK.Web Wartość zestawu SDK automatycznie dodaje odwołanie do platformy ASP.NET Core. Odwołanie pozwala aplikacji na używanie typów ASP.NET Core wymaganych do hostowania serwera.

Serwer gRPC można dodać do projektów non-ASP.NET Core przy użyciu następujących ustawień pliku projektu:

<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>

Poprzedni plik projektu:

  • Nie używa Microsoft.NET.SDK.Web jako zestawu SDK.
  • Dodaje odwołanie do struktury Microsoft.AspNetCore.App.
    • Odwołanie do struktury umożliwia aplikacjom spoza ASP.NET Core, takim jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms, korzystanie z interfejsów API ASP.NET Core.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Microsoft.AspNetCore.App (Korzystanie z platformy udostępnionej ASP.NET Core).

Integracja z interfejsami API platformy ASP.NET Core

Usługi gRPC mają pełny dostęp do takich funkcji ASP.NET Core jak wstrzykiwanie zależności (DI) i logowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja usługi gRPC może rozpoznawać inne usługi DI z dowolnym cyklem życia (Singleton, Scoped lub Przejściowy).

Rozwiązywanie problemów z protokołem HttpContext w metodach gRPC

Interfejs API gRPC zapewnia dostęp do niektórych danych komunikatów HTTP/2, takich jak metoda, host, nagłówek i przyrostki. Dostęp odbywa się za pośrednictwem argumentu przekazanego ServerCallContext do każdej metody gRPC:

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

ServerCallContext nie zapewnia pełnego dostępu do HttpContext wszystkich interfejsów API ASP.NET. Metoda rozszerzająca GetHttpContext zapewnia pełny dostęp do HttpContext reprezentującego bazowy komunikat HTTP/2 w API ASP.NET.

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
        });
    }
}

Dodatkowe zasoby

W tym dokumencie pokazano, jak rozpocząć pracę z usługami gRPC przy użyciu ASP.NET Core.

Wymagania wstępne

Wprowadzenie do usługi gRPC na platformie ASP.NET Core

Wyświetl lub pobierz przykładowy kod (jak pobrać).

Aby uzyskać szczegółowe instrukcje dotyczące tworzenia projektu gRPC, zobacz Wprowadzenie do usług gRPC.

Dodawanie usługi gRPC do aplikacji ASP.NET Core

Usługa gRPC wymaga pakietu Grpc.AspNetCore.

Konfigurowanie usługi gRPC

W pliku Startup.cs:

  • gRPC jest włączony za pomocą metody AddGrpc.
  • Każda usługa gRPC jest dodawana do potoku routingu za pomocą metody MapGrpcService.
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>();
        });
    }
}

Jeśli chcesz zobaczyć komentarze kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym w tym problemie z dyskusją w usłudze GitHub.

ASP.NET Podstawowe oprogramowanie pośredniczące i funkcje współużytkują potok routingu, dlatego można skonfigurować aplikację do obsługi dodatkowych procedur obsługi żądań. Dodatkowe programy obsługi żądań, takie jak kontrolery MVC, działają równolegle ze skonfigurowanymi usługami gRPC.

Opcje serwera

Usługi gRPC mogą być hostowane przez wszystkie wbudowane serwery ASP.NET Core.

  • Kestrel
  • Serwer testowy
  • Usługi IIS
  • HTTP.sys†

†Wymaga programu .NET 5 i Windows 11 Build 22000 lub Windows Server 2022 Build 20348 lub nowszego.

Aby uzyskać więcej informacji na temat wybierania odpowiedniego serwera dla aplikacji ASP.NET Core, zobacz Implementacje serwera sieci Web w ASP.NET Core.

Kestrel

Kestrel to międzyplatformowy serwer internetowy dla platformy ASP.NET Core. Kestrel koncentruje się na wysokiej wydajności i wykorzystaniu pamięci, ale nie ma niektórych zaawansowanych funkcji w HTTP.sys, takich jak udostępnianie portów.

Kestrel Punkty końcowe gRPC:

HTTP/2

GRPC wymaga protokołu HTTP/2. gRPC dla ASP.NET Core sprawdza, czy HttpRequest.Protocol jest zgodny z HTTP/2.

Kestrel obsługuje protokół HTTP/2 w większości nowoczesnych systemów operacyjnych. Kestrel Punkty końcowe są domyślnie skonfigurowane do obsługi połączeń HTTP/1.1 i HTTP/2.

TLS

Kestrel punkty końcowe używane na potrzeby gRPC powinny być zabezpieczone przy użyciu protokołu TLS. Podczas opracowywania, punkt końcowy zabezpieczony protokołem TLS jest tworzony automatycznie na https://localhost:5001, gdy jest obecny certyfikat dewelopera ASP.NET Core. Nie jest wymagana żadna konfiguracja. Prefiks https sprawdza, Kestrel czy punkt końcowy używa protokołu TLS.

W środowisku produkcyjnym protokół TLS musi być jawnie skonfigurowany. W poniższym appsettings.json przykładzie podano punkt końcowy HTTP/2 zabezpieczony przy użyciu protokołu TLS:

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

Alternatywnie Kestrel punkty końcowe można skonfigurować w programie Program.cs:

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>();
        });

Aby uzyskać więcej informacji na temat włączania protokołu TLS z Kestrel, zobacz Kestrel konfigurację punktu końcowego HTTPS.

Negocjowanie protokołu

Protokół TLS jest używany do czegoś więcej niż tylko zabezpieczania komunikacji. Protokół uzgadniania w warstwie aplikacji TLS (ALPN) jest używany do ustalania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów. Ta negocjacje określają, czy połączenie korzysta z protokołu HTTP/1.1, czy HTTP/2.

Jeśli punkt końcowy HTTP/2 jest skonfigurowany bez protokołu TLS, dla punktu końcowego ListenOptions.Protocols należy ustawić HttpProtocols.Http2. Punkt końcowy z wieloma protokołami, na HttpProtocols.Http1AndHttp2 przykład, nie może być używany bez protokołu TLS, ponieważ nie ma negocjacji. Wszystkie połączenia do niezabezpieczonego punktu końcowego domyślnie używają protokołu HTTP/1.1, a wywołania gRPC kończą się niepowodzeniem.

Aby uzyskać więcej informacji na temat włączania protokołu HTTP/2 i TLS z użyciem Kestrel, zobacz Kestrel konfigurację punktu końcowego.

Uwaga

System macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS przed platformą .NET 8. Dodatkowa konfiguracja jest wymagana do pomyślnego uruchomienia usług gRPC w systemie macOS w przypadku korzystania z platformy .NET 7 lub starszej wersji. Aby uzyskać więcej informacji, zobacz Nie można uruchomić aplikacji gRPC platformy ASP.NET Core w systemie macOS.

Hostowanie usługi gRPC w projektach non-ASP.NET Core

Serwer gRPC platformy ASP.NET Core jest zwykle tworzony na podstawie szablonu gRPC. Plik projektu utworzony przez szablon używa Microsoft.NET.SDK.Web jako SDK.

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

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

</Project>

Microsoft.NET.SDK.Web Wartość zestawu SDK automatycznie dodaje odwołanie do platformy ASP.NET Core. Odwołanie pozwala aplikacji na korzystanie z typów ASP.NET Core wymaganych do hostowania serwera.

Serwer gRPC można dodać do projektów non-ASP.NET Core przy użyciu następujących ustawień pliku projektu:

<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>

Poprzedni plik projektu:

  • Nie używa Microsoft.NET.SDK.Web jako zestawu SDK.
  • Dodaje odwołanie do struktury do Microsoft.AspNetCore.App.
    • Odwołanie do platformy umożliwia aplikacjom non-ASP.NET Core, takim jak usługi systemu Windows, aplikacje WPF lub aplikacje WinForms, korzystanie z interfejsów API ASP.NET Core.
    • Aplikacja może teraz używać interfejsów API ASP.NET Core do uruchamiania serwera ASP.NET Core.
  • Dodaje wymagania dotyczące usługi gRPC:

Aby uzyskać więcej informacji na temat korzystania z dokumentacji platformy, zobacz Microsoft.AspNetCore.App (Korzystanie z platformy udostępnionej ASP.NET Core).

Integracja z interfejsami API platformy ASP.NET Core

Usługi gRPC mają pełny dostęp do funkcji ASP.NET Core, takich jak wstrzykiwanie zależności (DI) i logowanie. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pomocą konstruktora:

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

Domyślnie implementacja serwisu gRPC może rozpoznawać inne serwisy DI z dowolnym okresem istnienia (Singleton, Scoped lub Przejściowy).

Rozwiązywanie problemów z protokołem HttpContext w metodach gRPC

Interfejs API gRPC zapewnia dostęp do niektórych danych wiadomości HTTP/2, takich jak metoda, host, nagłówek i trailery. Dostęp odbywa się za pośrednictwem argumentu przekazanego ServerCallContext do każdej metody gRPC:

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

ServerCallContext nie zapewnia pełnego dostępu do HttpContext wszystkich interfejsów API ASP.NET. Metoda rozszerzenia GetHttpContext zapewnia pełny dostęp do elementu HttpContext, który reprezentuje bazowy komunikat HTTP/2 w interfejsach API ASP.NET.

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
        });
    }
}

Dodatkowe zasoby