Usługi gRPC na platformie ASP.NET CoregRPC services with ASP.NET Core

W tym dokumencie przedstawiono sposób rozpoczynania pracy z usługami gRPC Services przy użyciu ASP.NET Core.This document shows how to get started with gRPC services using ASP.NET Core.

Ostrzeżenie

ASP.NET Core gRPC nie jest obecnie obsługiwana w Azure App Service lub IIS.ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. Implementacja protokołu HTTP/2 Http.Sys nie obsługuje nagłówków końcowych odpowiedzi HTTP, na których opiera się gRPC.The HTTP/2 implementation of Http.Sys does not support HTTP response trailing headers which gRPC relies on. Aby uzyskać więcej informacji, zobacz ten problemw serwisie GitHub.For more information, see this GitHub issue.

Wymagania wstępnePrerequisites

Wprowadzenie do usługi gRPC na platformie ASP.NET CoreGet started with gRPC service in ASP.NET Core

Wyświetlanie lub Pobieranie przykładowego kodu (jak pobrać).View or download sample code (how to download).

Szczegółowe instrukcje dotyczące tworzenia projektu gRPC można znaleźć w temacie Wprowadzenie do usług gRPC Services .See Get started with gRPC services for detailed instructions on how to create a gRPC project.

Dodawanie usług gRPC do aplikacji ASP.NET CoreAdd gRPC services to an ASP.NET Core app

gRPC wymaga pakietu gRPC. AspNetCore .gRPC requires the Grpc.AspNetCore package.

Konfigurowanie gRPCConfigure gRPC

W Startup.cs :In Startup.cs :

  • gRPC jest włączona z AddGrpc metodą.gRPC is enabled with the AddGrpc method.
  • Każda usługa gRPC jest dodawana do potoku routingu za pomocą MapGrpcService metody.Each gRPC service is added to the routing pipeline through the MapGrpcService method.
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 do kodu przetłumaczone na języki inne niż angielski, poinformuj nas o tym problemie z dyskusjąw witrynie GitHub.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

ASP.NET Core middlewares i funkcje korzystają z potoku routingu, w związku z czym aplikacja może być skonfigurowana w taki sposób, aby obsługiwała dodatkowe procedury obsługi żądań.ASP.NET Core middlewares and features share the routing pipeline, therefore an app can be configured to serve additional request handlers. Dodatkowe programy obsługi żądań, takie jak kontrolery MVC, pracują równolegle ze skonfigurowanymi usługami gRPC.The additional request handlers, such as MVC controllers, work in parallel with the configured gRPC services.

Konfigurowanie KestrelConfigure Kestrel

Punkty końcowe Kestrel gRPC:Kestrel gRPC endpoints:

HTTP/2HTTP/2

gRPC wymaga protokołu HTTP/2.gRPC requires HTTP/2. gRPC dla ASP.NET Core sprawdza poprawność elementu HttpRequest. Protocol HTTP/2 .gRPC for ASP.NET Core validates HttpRequest.Protocol is HTTP/2.

Kestrel obsługuje protokół HTTP/2 w większości nowoczesnych systemów operacyjnych.Kestrel supports HTTP/2 on most modern operating systems. Punkty końcowe Kestrel są domyślnie skonfigurowane do obsługi połączeń HTTP/1.1 i HTTP/2.Kestrel endpoints are configured to support HTTP/1.1 and HTTP/2 connections by default.

TLSTLS

Punkty końcowe Kestrel używane dla gRPC powinny być zabezpieczone przy użyciu protokołu TLS.Kestrel endpoints used for gRPC should be secured with TLS. W trakcie opracowywania, punkt końcowy zabezpieczony przy użyciu protokołu TLS jest automatycznie tworzony na https://localhost:5001 czas, gdy obecny jest ASP.NET Core certyfikat deweloperski.In development, an endpoint secured with TLS is automatically created at https://localhost:5001 when the ASP.NET Core development certificate is present. Nie jest wymagana żadna konfiguracja.No configuration is required. httpsPrefiks sprawdza, czy punkt końcowy Kestrel korzysta z protokołu TLS.An https prefix verifies the Kestrel endpoint is using TLS.

W środowisku produkcyjnym należy jawnie skonfigurować protokół TLS.In production, TLS must be explicitly configured. W poniższym appsettings.json przykładzie jest dostępny punkt końcowy HTTP/2 zabezpieczony przy użyciu protokołu TLS:In the following appsettings.json example, an HTTP/2 endpoint secured with TLS is provided:

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

Alternatywnie można skonfigurować punkty końcowe Kestrel w program.cs :Alternatively, Kestrel endpoints can be configured in 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>();
        });

Negocjowanie protokołuProtocol negotiation

Protokół TLS jest używany przez więcej niż Zabezpieczanie komunikacji.TLS is used for more than securing communication. Uzgadnianie protokołu warstwy aplikacji TLS (ClientHello alpn) służy do negocjowania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów.The TLS Application-Layer Protocol Negotiation (ALPN) handshake is used to negotiate the connection protocol between the client and the server when an endpoint supports multiple protocols. Ta negocjacja określa, czy połączenie używa protokołu HTTP/1.1 czy HTTP/2.This negotiation determines whether the connection uses HTTP/1.1 or HTTP/2.

Jeśli punkt końcowy protokołu HTTP/2 jest skonfigurowany bez protokołu TLS, ListenOptions. protokoły punktu końcowego muszą mieć ustawioną wartość HttpProtocols.Http2 .If an HTTP/2 endpoint is configured without TLS, the endpoint's ListenOptions.Protocols must be set to HttpProtocols.Http2. Punkt końcowy z wieloma protokołami (na przykład HttpProtocols.Http1AndHttp2 ) nie może być używany bez protokołu TLS, ponieważ nie ma negocjacji.An endpoint with multiple protocols (for example, HttpProtocols.Http1AndHttp2) can't be used without TLS because there is no negotiation. Wszystkie połączenia z niezabezpieczonym punktem końcowym domyślne do protokołu HTTP/1.1 i wywołania gRPC kończą się niepowodzeniem.All connections to the unsecured endpoint default to HTTP/1.1, and gRPC calls fail.

Aby uzyskać więcej informacji na temat włączania protokołów HTTP/2 i TLS przy użyciu usługi Kestrel, zobacz Konfiguracja punktu końcowego Kestrel.For more information on enabling HTTP/2 and TLS with Kestrel, see Kestrel endpoint configuration.

Uwaga

Program macOS nie obsługuje ASP.NET Core gRPC z protokołem TLS.macOS doesn't support ASP.NET Core gRPC with TLS. Aby pomyślnie uruchomić usługi gRPC Services w usłudze macOS, wymagana jest dodatkowa konfiguracja.Additional configuration is required to successfully run gRPC services on macOS. Aby uzyskać więcej informacji, zobacz nie można uruchomić aplikacji ASP.NET Core gRPC w witrynie macOS.For more information, see Unable to start ASP.NET Core gRPC app on macOS.

Integracja z interfejsami API ASP.NET CoreIntegration with ASP.NET Core APIs

usługi gRPC mają pełny dostęp do funkcji ASP.NET Core, takich jak iniekcja zależności (di) i Rejestrowanie.gRPC services have full access to the ASP.NET Core features such as Dependency Injection (DI) and Logging. Na przykład implementacja usługi może rozpoznać usługę rejestratora z kontenera DI za pośrednictwem konstruktora:For example, the service implementation can resolve a logger service from the DI container via the constructor:

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

Domyślnie implementacja usługi gRPC może rozwiązywać inne usługi DI z dowolnym okresem istnienia (pojedynczym, zakresowym lub przejściowym).By default, the gRPC service implementation can resolve other DI services with any lifetime (Singleton, Scoped, or Transient).

Rozwiąż element HttpContext w metodach gRPCResolve HttpContext in gRPC methods

Interfejs API gRPC zapewnia dostęp do niektórych danych komunikatów HTTP/2, takich jak metoda, host, nagłówek i przyczepy.The gRPC API provides access to some HTTP/2 message data, such as the method, host, header, and trailers. Dostęp odbywa się za pomocą ServerCallContext argumentu przesłanego do każdej metody gRPC:Access is through the ServerCallContext argument passed to each gRPC method:

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.ServerCallContext does not provide full access to HttpContext in all ASP.NET APIs. GetHttpContextMetoda rozszerzająca zapewnia pełny dostęp do HttpContext reprezentowania podstawowego komunikatu http/2 w interfejsach API ASP.NET:The GetHttpContext extension method provides full access to the HttpContext representing the underlying HTTP/2 message in ASP.NET APIs:

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