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

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

Advertencia

ASP.NET Core gRPC tiene requisitos adicionales para su uso con Azure App Service o IIS.ASP.NET Core gRPC has extra requirements for being used with Azure App Service or IIS. Para obtener más información sobre dónde se puede usar gRPC, vea gRPC en plataformas compatibles con .NET.For more information on where gRPC can be used, see gRPC en plataformas compatibles con .NET.

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

Consulte el artículo Introducción a los servicios gRPC para obtener instrucciones detalladas sobre cómo crear un proyecto gRPC.See Get started with gRPC services for detailed instructions on how to create a gRPC project.

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

Si quiere que los comentarios de código se traduzcan en más idiomas además del inglés, háganoslo saber en este problema de debate de GitHub.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

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

Opciones de servidorServer options

Los servicios gRPC se pueden hospedar por todos los servidores de ASP.NET Core integrados.gRPC services can be hosted by all built-in ASP.NET Core servers.

  • KestrelKestrel
  • TestServerTestServer
  • IIS†IIS†
  • HTTP.sys‡HTTP.sys‡

†IIS requiere .NET 5 y Windows 10, compilación 20300.1000 o posterior.†IIS requires .NET 5 and Windows 10 Build 20300.1000 or later.
‡HTTP.sys requiere .NET 5 y Windows 10, compilación 19529 o posterior.‡HTTP.sys requires .NET 5 and Windows 10 Build 19529 or later.

Las versiones de la compilación de Windows 10 anteriores pueden requerir el uso de una compilación para Windows Insider.The preceding Windows 10 Build versions may require the use of a Windows Insider build.

Para obtener más información sobre cómo elegir el servidor adecuado para una aplicación ASP.NET Core, vea Implementaciones de servidores web en ASP.NET Core.For more information about choosing the right server for an ASP.NET Core app, see Implementaciones de servidores web en ASP.NET Core.

KestrelKestrel

Kestrel es un servidor web multiplataforma de ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel proporciona el mejor rendimiento y uso de memoria, pero carece de algunas de las características avanzadas de HTTP.sys (como el uso compartido de puertos).Kestrel provides the best performance and memory utilization, but it doesn't have some of the advanced features in HTTP.sys such as port sharing.

Los puntos de conexión para gRPC de Kestrel:Kestrel gRPC endpoints:

HTTP/2HTTP/2

gRPC requiere HTTP/2.gRPC requires HTTP/2. gRPC para ASP.NET Core valida que HttpRequest.Protocol sea 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 la fase de desarrollo, se crea automáticamente un punto de conexión protegido con TLS en https://localhost:5001 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 prefijo https comprueba que el punto de conexión de Kestrel está usando TLS.An https prefix verifies the Kestrel endpoint is using TLS.

En un entorno de producción, se debe configurar TLS explícitamente.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 del protocoloProtocol negotiation

TLS no solo se usa para proteger la comunicación.TLS is used for more than securing communication. El protocolo de enlace Application-Layer Protocol Negotiation (ALPN) de TLS se usa para negociar el protocolo de conexión entre el cliente y el servidor cuando un punto de conexión 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 usa 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 valor ListenOptions.Protocols del punto de conexión debe establecerse en HttpProtocols.Http2.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 varios protocolos (por ejemplo, HttpProtocols.Http1AndHttp2) 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's no negotiation. Se usa HTTP/1.1 de forma predeterminada para todas las conexiones al punto de conexión no seguro y se produce un error en 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 la sección sobre la 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.

IISIIS

Internet Information Services (IIS) es un servidor web flexible, seguro y administrable para el hospedaje de aplicaciones web, incluido ASP.NET Core.Internet Information Services (IIS) is a flexible, secure and manageable Web Server for hosting web apps, including ASP.NET Core. Se necesitan .NET 5 y la compilación 20300.1000, o versiones posteriores, de Windows 10, para hospedar los servicios gRPC con IIS, lo que puede requerir el uso de una compilación para Windows Insider..NET 5 and Windows 10 Build 20300.1000 or later are required to host gRPC services with IIS, which may require the use of a Windows Insider build.

IIS debe estar configurado para usar TLS y HTTP/2.IIS must be configured to use TLS and HTTP/2. Para obtener más información, vea Uso de ASP.NET Core con HTTP/2 en IIS.For more information, see Uso de ASP.NET Core con HTTP/2 en IIS.

HTTP.sysHTTP.sys

HTTP.sys es un servidor web de ASP.NET Core que solo se ejecuta en Windows.HTTP.sys is a web server for ASP.NET Core that only runs on Windows. Se necesitan .NET 5 y la compilación 19529, o versiones posteriores, de Windows 10 para hospedar los servicios gRPC con HTTP.sys, lo que puede requerir el uso de una compilación para Windows Insider..NET 5 and Windows 10 Build 19529 or later are required to host gRPC services with HTTP.sys, which may require the use of a Windows Insider build.

HTTP.sys debe estar configurado para usar TLS y HTTP/2.HTTP.sys must be configured to use TLS and HTTP/2. Para obtener más información, vea Compatibilidad con HTTP/2 del servidor web HTTP.sys.For more information, see HTTP.sys web server HTTP/2 support.

KestrelKestrel

Kestrel es un servidor web multiplataforma de ASP.NET Core.Kestrel is a cross-platform web server for ASP.NET Core. Kestrel proporciona el mejor rendimiento y uso de memoria, pero carece de algunas de las características avanzadas de HTTP.sys (como el uso compartido de puertos).Kestrel provides the best performance and memory utilization, but it doesn't have some of the advanced features in HTTP.sys such as port sharing.

Los puntos de conexión para gRPC de Kestrel:Kestrel gRPC endpoints:

HTTP/2HTTP/2

gRPC requiere HTTP/2.gRPC requires HTTP/2. gRPC para ASP.NET Core valida que HttpRequest.Protocol sea 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 la fase de desarrollo, se crea automáticamente un punto de conexión protegido con TLS en https://localhost:5001 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 prefijo https comprueba que el punto de conexión de Kestrel está usando TLS.An https prefix verifies the Kestrel endpoint is using TLS.

En un entorno de producción, se debe configurar TLS explícitamente.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 del protocoloProtocol negotiation

TLS no solo se usa para proteger la comunicación.TLS is used for more than securing communication. El protocolo de enlace Application-Layer Protocol Negotiation (ALPN) de TLS se usa para negociar el protocolo de conexión entre el cliente y el servidor cuando un punto de conexión 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 usa 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 valor ListenOptions.Protocols del punto de conexión debe establecerse en HttpProtocols.Http2.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 varios protocolos (por ejemplo, HttpProtocols.Http1AndHttp2) 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's no negotiation. Se usa HTTP/1.1 de forma predeterminada para todas las conexiones al punto de conexión no seguro y se produce un error en 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 la sección sobre la 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 las API de ASP.NET CoreIntegration with ASP.NET Core APIs

Los servicios gRPC tienen acceso total a las características de ASP.NET Core, como la inserción de dependencias (ID) y los registros.gRPC services have full access to the ASP.NET Core features such as Dependency Injection (DI) and Logging. Por ejemplo, la implementación de los servicios puede resolver un servicio del registrador desde el contenedor de inserción de dependencias 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 de los servicios gRPC puede resolver otros servicios de inserción de dependencias con cualquier duración (singleton, restringida o transitoria).By default, the gRPC service implementation can resolve other DI services with any lifetime (Singleton, Scoped, or Transient).

Resolución de HttpContext en métodos gRPCResolve HttpContext in gRPC methods

La API de 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 a través del argumento ServerCallContext 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
        });
    }
}

ServerCallContext no proporciona acceso completo a HttpContext en todas las API de ASP.NET.ServerCallContext doesn't provide full access to HttpContext in all ASP.NET APIs. Sin embargo, el método de extensión GetHttpContext sí proporciona acceso completo al objeto HttpContext 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
        });
    }
}

Recursos adicionalesAdditional resources