Servicios gRPC con ASP.NET CoregRPC services with ASP.NET Core

En este documento se muestra cómo empezar a trabajar con gRPC Services mediante ASP.NET Core.This document shows how to get started with gRPC services using ASP.NET Core.

Requisitos previosPrerequisites

Introducción al servicio gRPC en ASP.NET CoreGet started with gRPC service in ASP.NET Core

Vea o descargue el código de ejemplo (cómo descargarlo).View or download sample code (how to download).

Vea Introducción a gRPC Services para obtener instrucciones detalladas sobre cómo crear un proyecto de gRPC.See Get started with gRPC services for detailed instructions on how to create a gRPC project.

Incorporación de gRPC Services a una aplicación ASP.NET CoreAdd gRPC services to an ASP.NET Core app

gRPC requiere el paquete gRPC. AspNetCore .gRPC requires the Grpc.AspNetCore package.

Configuración de gRPCConfigure gRPC

En Startup.cs:In Startup.cs:

  • gRPC se habilita con el AddGrpc método.gRPC is enabled with the AddGrpc method.
  • Cada servicio gRPC se agrega a la canalización de enrutamiento MapGrpcService a través del método.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>();
        });
    }
}

ASP.NET Core los middleware y las características comparten la canalización de enrutamiento, por lo que se puede configurar una aplicación para que atienda a los controladores de solicitud adicionales.ASP.NET Core middlewares and features share the routing pipeline, therefore an app can be configured to serve additional request handlers. Los controladores de solicitud adicionales, como los controladores MVC, funcionan en paralelo con los servicios gRPC configurados.The additional request handlers, such as MVC controllers, work in parallel with the configured gRPC services.

Configuración de KestrelConfigure Kestrel

Puntos de conexión de Kestrel gRPC:Kestrel gRPC endpoints:

HTTP/2HTTP/2

gRPC requiere HTTP/2.gRPC requires HTTP/2. gRPC for ASP.NET Core valida HttpRequest. Protocol es HTTP/2.gRPC for ASP.NET Core validates HttpRequest.Protocol is HTTP/2.

Kestrel admite http/2 en la mayoría de los sistemas operativos modernos.Kestrel supports HTTP/2 on most modern operating systems. Los puntos de conexión de Kestrel se configuran para admitir conexiones HTTP/1.1 y HTTP/2 de forma predeterminada.Kestrel endpoints are configured to support HTTP/1.1 and HTTP/2 connections by default.

TLSTLS

Los puntos de conexión de Kestrel usados para gRPC deben protegerse con TLS.Kestrel endpoints used for gRPC should be secured with TLS. En el desarrollo, se crea https://localhost:5001 automáticamente un punto de conexión protegido con TLS cuando el certificado de desarrollo de ASP.net Core está presente.In development, an endpoint secured with TLS is automatically created at https://localhost:5001 when the ASP.NET Core development certificate is present. No se requiere ninguna configuración.No configuration is required. Un https prefijo comprueba que el punto de conexión Kestrel usa TLS.An https prefix verifies the Kestrel endpoint is using TLS.

En producción, se debe configurar explícitamente TLS.In production, TLS must be explicitly configured. En el siguiente ejemplo de appSettings. JSON , se proporciona un punto de conexión http/2 protegido con 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>"
        }
      }
    }
  }
}

Como alternativa, se pueden configurar puntos de conexión de Kestrel en 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>();
        });

Negociación de protocoloProtocol negotiation

TLS se usa para más que proteger la comunicación.TLS is used for more than securing communication. El protocolo de enlace de negociación del Protocolo de capa de aplicación (ALPN) de TLS se usa para negociar el protocolo de conexión entre el cliente y el servidor cuando un extremo admite varios protocolos.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. Esta negociación determina si la conexión utiliza HTTP/1.1 o HTTP/2.This negotiation determines whether the connection uses HTTP/1.1 or HTTP/2.

Si un punto de conexión HTTP/2 se configura sin TLS, el ListenOptions. Protocols del punto de HttpProtocols.Http2conexión debe establecerse en.If an HTTP/2 endpoint is configured without TLS, the endpoint's ListenOptions.Protocols must be set to HttpProtocols.Http2. No se puede usar un punto de conexión con HttpProtocols.Http1AndHttp2varios protocolos (por ejemplo,) sin TLS porque no hay ninguna negociación.An endpoint with multiple protocols (for example, HttpProtocols.Http1AndHttp2) can't be used without TLS because there is no negotiation. Se produce un error en todas las conexiones al extremo no seguro de forma predeterminada a HTTP/1.1 y a las llamadas a gRPC.All connections to the unsecured endpoint default to HTTP/1.1, and gRPC calls fail.

Para obtener más información sobre cómo habilitar HTTP/2 y TLS con Kestrel, consulte configuración del punto de conexión de Kestrel.For more information on enabling HTTP/2 and TLS with Kestrel, see Kestrel endpoint configuration.

Nota

macOS no admite gRPC de ASP.NET Core con TLS.macOS doesn't support ASP.NET Core gRPC with TLS. Se requiere configuración adicional para ejecutar correctamente servicios gRPC en macOS.Additional configuration is required to successfully run gRPC services on macOS. Para obtener más información, vea No se puede iniciar la aplicación gRPC de ASP.NET Core en macOS.For more information, see Unable to start ASP.NET Core gRPC app on macOS.

Integración con API de ASP.NET CoreIntegration with ASP.NET Core APIs

los servicios de gRPC tienen acceso completo a las características de ASP.NET Core, como la inserción de dependencias (di) y el registro.gRPC services have full access to the ASP.NET Core features such as Dependency Injection (DI) and Logging. Por ejemplo, la implementación del servicio puede resolver un servicio del registrador a partir del contenedor de DI mediante el constructor: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)
    {
    }
}

De forma predeterminada, la implementación del servicio gRPC puede resolver otros servicios de DI con cualquier duración (singleton, ámbito o transitorio).By default, the gRPC service implementation can resolve other DI services with any lifetime (Singleton, Scoped, or Transient).

Resolver HttpContext en métodos gRPCResolve HttpContext in gRPC methods

La API gRPC proporciona acceso a algunos datos de mensajes HTTP/2, como el método, el host, el encabezado y los finalizadores.The gRPC API provides access to some HTTP/2 message data, such as the method, host, header, and trailers. El acceso se realiza ServerCallContext a través del argumento que se pasa a cada método 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
        });
    }
}

ServerCallContextno proporciona acceso completo a HttpContext en todas las API de ASP.net.ServerCallContext does not provide full access to HttpContext in all ASP.NET APIs. El GetHttpContext método de extensión proporciona acceso completo HttpContext a que representa el mensaje http/2 subyacente en las API de 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
        });
    }
}

gRPC no es compatible con Azure App ServicegRPC not supported on Azure App Service

Advertencia

Actualmente, gRPC de ASP.NET Core no es compatible con Azure App Service ni IIS.ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. La implementación HTTP/2 de Http.Sys no admite los encabezados finales de la respuesta HTTP en los que se basa gRPC.The HTTP/2 implementation of Http.Sys does not support HTTP response trailing headers which gRPC relies on. Para más información, consulte este problema de GitHub.For more information, see this GitHub issue.

Recursos adicionalesAdditional resources