Compartir vía

Servicios gRPC con ASP.NET Core

  • Artículo

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión .NET 8 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulte la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulte la versión .NET 8 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulte la versión .NET 8 de este artículo.

En este documento se muestra cómo empezar a usar servicios gRPC con ASP.NET Core.

Requisitos previos

Introducción al servicio gRPC en ASP.NET Core

Vea o descargue el código de ejemplo (cómo descargarlo).

Consulte el artículo Introducción a los servicios gRPC para obtener instrucciones detalladas sobre cómo crear un proyecto gRPC.

Incorporación de servicios gRPC a una aplicación de ASP.NET Core

gRPC requiere el paquete Grpc.AspNetCore.

Configuración de gRPC

En Program.cs:

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

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.

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. Los controladores de solicitudes adicionales, como los controladores MVC, trabajan en paralelo con los servicios gRPC configurados.

Opciones de servidor

Los servicios gRPC se pueden hospedar por todos los servidores de ASP.NET Core integrados.

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

†Requiere .NET 5 y Windows 11, compilación 22000, o Windows Server 2022, compilación 20348 o posterior.

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.

Kestrel

Kestrel es un servidor web multiplataforma de ASP.NET Core. Kestrel se centra en el rendimiento y uso de memoria elevados, pero carece de algunas de las características avanzadas de HTTP.sys como el uso compartido de puertos.

Puntos de conexión gRPC de Kestrel:

HTTP/2

gRPC requiere HTTP/2. gRPC para ASP.NET Core valida que HttpRequest.Protocol sea HTTP/2.

Kestreladmite HTTP/2 en la mayoría de los sistemas operativos modernos. Los puntos de conexión de Kestrel se configuran para admitir conexiones HTTP/1.1 y HTTP/2 de forma predeterminada.

TLS

Los puntos de conexión de Kestrel usados para gRPC deben protegerse con 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. No se requiere ninguna configuración. Un prefijo https comprueba que el punto de conexión de Kestrel está usando TLS.

En un entorno de producción, se debe configurar TLS explícitamente. En el siguiente ejemplo de appsettings.json , se proporciona un punto de conexión HTTP/2 protegido con TLS:

{
  "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:

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

Para más información sobre cómo habilitar TLS con Kestrel, vea Configuración de los puntos de conexión HTTPS para Kestrel.

Negociación del protocolo

TLS no solo se usa para proteger la comunicación. 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. Esta negociación determina si la conexión usa HTTP/1.1 o 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. No se puede usar un punto de conexión con varios protocolos (por ejemplo, HttpProtocols.Http1AndHttp2) sin TLS, porque no hay ninguna negociación. 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.

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.

Nota

macOS no admite gRPC de ASP.NET Core con TLS anterior a .NET 8. Se requiere configuración adicional para ejecutar correctamente servicios gRPC en macOS cuando se usa .NET 7 o anterior. Para obtener más información, vea No se puede iniciar la aplicación gRPC de ASP.NET Core en macOS.

IIS

Internet Information Services (IIS) es un servidor web flexible, seguro y administrable para el hospedaje de aplicaciones web, incluido ASP.NET Core. Se requiere .NET 5 y Windows 11 en compilación 22000 o Windows Server 2022 en compilación 20348 o posterior para hospedar servicios gRPC con IIS.

IIS debe estar configurado para usar TLS y HTTP/2. Para obtener más información, vea Uso de ASP.NET Core con HTTP/2 en IIS.

HTTP.sys

HTTP.sys es un servidor web de ASP.NET Core que solo se ejecuta en Windows. Se requiere .NET 5 y Windows 11 en compilación 22000 o Windows Server 2022 en compilación 20348 o posterior para hospedar servicios gRPC con HTTP.sys.

HTTP.sys debe estar configurado para usar TLS y HTTP/2. Para obtener más información, vea Compatibilidad con HTTP/2 del servidor web HTTP.sys.

Hospedaje de gRPC en proyectos que no son de ASP.NET Core

Normalmente, un servidor gRPC de ASP.NET Core se crea a partir de la plantilla de gRPC. El archivo de proyecto creado por la plantilla usa Microsoft.NET.SDK.Web como 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>

El valor del SDK Microsoft.NET.SDK.Web agrega automáticamente una referencia al marco ASP.NET Core. La referencia permite que la aplicación use tipos de ASP.NET Core necesarios para hospedar un servidor.

Puede agregar un servidor gRPC a proyectos que no son de ASP.NET Core con la siguiente configuración del archivo de proyecto:

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

El archivo del proyecto anterior:

  • No usa Microsoft.NET.SDK.Web como el SDK.
  • Agrega una referencia de marco a Microsoft.AspNetCore.App.
    • La referencia de marco permite a aplicaciones no ASP.NET Core, como servicios de Windows, aplicaciones WPF o aplicaciones WinForms, usar API ASP.NET Core.
    • La aplicación ahora puede usar API de ASP.NET Core para iniciar un servidor de ASP.NET Core.
  • Agrega requisitos de gRPC:

Para obtener más información sobre cómo agregar la referencia del marco de Microsoft.AspNetCore.App, vea Uso del marco compartido de ASP.NET Core.

Integración con las API de ASP.NET Core

Los servicios gRPC tienen acceso total a las características de ASP.NET Core, como la inserción de dependencias (ID) y los registros. 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:

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

Resolución de HttpContext en métodos gRPC

La API de gRPC proporciona acceso a algunos datos de mensajes HTTP/2, como el método, el host, el encabezado y los finalizadores. El acceso se realiza a través del argumento ServerCallContext que se pasa a cada método 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 no proporciona acceso completo a HttpContext en todas las API de ASP.NET. 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:

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 adicionales

En este documento se muestra cómo empezar a usar servicios gRPC con ASP.NET Core.

Requisitos previos

Introducción al servicio gRPC en ASP.NET Core

Vea o descargue el código de ejemplo (cómo descargarlo).

Consulte el artículo Introducción a los servicios gRPC para obtener instrucciones detalladas sobre cómo crear un proyecto gRPC.

Incorporación de servicios gRPC a una aplicación de ASP.NET Core

gRPC requiere el paquete Grpc.AspNetCore.

Configuración de gRPC

En Program.cs:

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

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.

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. Los controladores de solicitudes adicionales, como los controladores MVC, trabajan en paralelo con los servicios gRPC configurados.

Opciones de servidor

Los servicios gRPC se pueden hospedar por todos los servidores de ASP.NET Core integrados.

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

†Requiere .NET 5 y Windows 11, compilación 22000, o Windows Server 2022, compilación 20348 o posterior.

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.

Kestrel

Kestrel es un servidor web multiplataforma de ASP.NET Core. Kestrel se centra en el rendimiento y uso de memoria elevados, pero carece de algunas de las características avanzadas de HTTP.sys como el uso compartido de puertos.

Puntos de conexión gRPC de Kestrel:

HTTP/2

gRPC requiere HTTP/2. gRPC para ASP.NET Core valida que HttpRequest.Protocol sea HTTP/2.

Kestreladmite HTTP/2 en la mayoría de los sistemas operativos modernos. Los puntos de conexión de Kestrel se configuran para admitir conexiones HTTP/1.1 y HTTP/2 de forma predeterminada.

TLS

Los puntos de conexión de Kestrel usados para gRPC deben protegerse con 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. No se requiere ninguna configuración. Un prefijo https comprueba que el punto de conexión de Kestrel está usando TLS.

En un entorno de producción, se debe configurar TLS explícitamente. En el siguiente ejemplo de appsettings.json , se proporciona un punto de conexión HTTP/2 protegido con TLS:

{
  "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:

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

Para más información sobre cómo habilitar TLS con Kestrel, vea Configuración de los puntos de conexión HTTPS para Kestrel.

Negociación del protocolo

TLS no solo se usa para proteger la comunicación. 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. Esta negociación determina si la conexión usa HTTP/1.1 o 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. No se puede usar un punto de conexión con varios protocolos (por ejemplo, HttpProtocols.Http1AndHttp2) sin TLS, porque no hay ninguna negociación. 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.

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.

Nota

macOS no admite gRPC de ASP.NET Core con TLS anterior a .NET 8. Se requiere configuración adicional para ejecutar correctamente servicios gRPC en macOS cuando se usa .NET 7 o anterior. Para obtener más información, vea No se puede iniciar la aplicación gRPC de ASP.NET Core en macOS.

IIS

Internet Information Services (IIS) es un servidor web flexible, seguro y administrable para el hospedaje de aplicaciones web, incluido ASP.NET Core. Se requiere .NET 5 y Windows 11 en compilación 22000 o Windows Server 2022 en compilación 20348 o posterior para hospedar servicios gRPC con IIS.

IIS debe estar configurado para usar TLS y HTTP/2. Para obtener más información, vea Uso de ASP.NET Core con HTTP/2 en IIS.

HTTP.sys

HTTP.sys es un servidor web de ASP.NET Core que solo se ejecuta en Windows. Se requiere .NET 5 y Windows 11 en compilación 22000 o Windows Server 2022 en compilación 20348 o posterior para hospedar servicios gRPC con HTTP.sys.

HTTP.sys debe estar configurado para usar TLS y HTTP/2. Para obtener más información, vea Compatibilidad con HTTP/2 del servidor web HTTP.sys.

Hospedaje de gRPC en proyectos que no son de ASP.NET Core

Normalmente, un servidor gRPC de ASP.NET Core se crea a partir de la plantilla de gRPC. El archivo de proyecto creado por la plantilla usa Microsoft.NET.SDK.Web como 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>

El valor del SDK Microsoft.NET.SDK.Web agrega automáticamente una referencia al marco ASP.NET Core. La referencia permite que la aplicación use tipos de ASP.NET Core necesarios para hospedar un servidor.

Puede agregar un servidor gRPC a proyectos que no son de ASP.NET Core con la siguiente configuración del archivo de proyecto:

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

El archivo del proyecto anterior:

  • No usa Microsoft.NET.SDK.Web como el SDK.
  • Agrega una referencia de marco a Microsoft.AspNetCore.App.
    • La referencia de marco permite a aplicaciones no ASP.NET Core, como servicios de Windows, aplicaciones WPF o aplicaciones WinForms, usar API ASP.NET Core.
    • La aplicación ahora puede usar API de ASP.NET Core para iniciar un servidor de ASP.NET Core.
  • Agrega requisitos de gRPC:

Para obtener más información sobre cómo agregar la referencia del marco de Microsoft.AspNetCore.App, vea Uso del marco compartido de ASP.NET Core.

Integración con las API de ASP.NET Core

Los servicios gRPC tienen acceso total a las características de ASP.NET Core, como la inserción de dependencias (ID) y los registros. 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:

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

Resolución de HttpContext en métodos gRPC

La API de gRPC proporciona acceso a algunos datos de mensajes HTTP/2, como el método, el host, el encabezado y los finalizadores. El acceso se realiza a través del argumento ServerCallContext que se pasa a cada método 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 no proporciona acceso completo a HttpContext en todas las API de ASP.NET. 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:

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 adicionales

En este documento se muestra cómo empezar a usar servicios gRPC con ASP.NET Core.

Requisitos previos

Introducción al servicio gRPC en ASP.NET Core

Vea o descargue el código de ejemplo (cómo descargarlo).

Consulte el artículo Introducción a los servicios gRPC para obtener instrucciones detalladas sobre cómo crear un proyecto gRPC.

Incorporación de servicios gRPC a una aplicación de ASP.NET Core

gRPC requiere el paquete Grpc.AspNetCore.

Configuración de gRPC

En Program.cs:

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

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.

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. Los controladores de solicitudes adicionales, como los controladores MVC, trabajan en paralelo con los servicios gRPC configurados.

Opciones de servidor

Los servicios gRPC se pueden hospedar por todos los servidores de ASP.NET Core integrados.

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

†Requiere .NET 5 y Windows 11, compilación 22000, o Windows Server 2022, compilación 20348 o posterior.

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.

Kestrel

Kestrel es un servidor web multiplataforma de ASP.NET Core. Kestrel se centra en el rendimiento y uso de memoria elevados, pero carece de algunas de las características avanzadas de HTTP.sys como el uso compartido de puertos.

Puntos de conexión gRPC de Kestrel:

HTTP/2

gRPC requiere HTTP/2. gRPC para ASP.NET Core valida que HttpRequest.Protocol sea HTTP/2.

Kestreladmite HTTP/2 en la mayoría de los sistemas operativos modernos. Los puntos de conexión de Kestrel se configuran para admitir conexiones HTTP/1.1 y HTTP/2 de forma predeterminada.

TLS

Los puntos de conexión de Kestrel usados para gRPC deben protegerse con 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. No se requiere ninguna configuración. Un prefijo https comprueba que el punto de conexión de Kestrel está usando TLS.

En un entorno de producción, se debe configurar TLS explícitamente. En el siguiente ejemplo de appsettings.json , se proporciona un punto de conexión HTTP/2 protegido con TLS:

{
  "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:

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

Para más información sobre cómo habilitar TLS con Kestrel, vea Configuración de los puntos de conexión HTTPS para Kestrel.

Negociación del protocolo

TLS no solo se usa para proteger la comunicación. 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. Esta negociación determina si la conexión usa HTTP/1.1 o 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. No se puede usar un punto de conexión con varios protocolos (por ejemplo, HttpProtocols.Http1AndHttp2) sin TLS, porque no hay ninguna negociación. 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.

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.

Nota

macOS no admite gRPC de ASP.NET Core con TLS anterior a .NET 8. Se requiere configuración adicional para ejecutar correctamente servicios gRPC en macOS cuando se usa .NET 7 o anterior. Para obtener más información, vea No se puede iniciar la aplicación gRPC de ASP.NET Core en macOS.

IIS

Internet Information Services (IIS) es un servidor web flexible, seguro y administrable para el hospedaje de aplicaciones web, incluido ASP.NET Core. Se requiere .NET 5 y Windows 11 en compilación 22000 o Windows Server 2022 en compilación 20348 o posterior para hospedar servicios gRPC con IIS.

IIS debe estar configurado para usar TLS y HTTP/2. Para obtener más información, vea Uso de ASP.NET Core con HTTP/2 en IIS.

HTTP.sys

HTTP.sys es un servidor web de ASP.NET Core que solo se ejecuta en Windows. Se requiere .NET 5 y Windows 11 en compilación 22000 o Windows Server 2022 en compilación 20348 o posterior para hospedar servicios gRPC con HTTP.sys.

HTTP.sys debe estar configurado para usar TLS y HTTP/2. Para obtener más información, vea Compatibilidad con HTTP/2 del servidor web HTTP.sys.

Hospedaje de gRPC en proyectos que no son de ASP.NET Core

Normalmente, un servidor gRPC de ASP.NET Core se crea a partir de la plantilla de gRPC. El archivo de proyecto creado por la plantilla usa Microsoft.NET.SDK.Web como 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>

El valor del SDK Microsoft.NET.SDK.Web agrega automáticamente una referencia al marco ASP.NET Core. La referencia permite que la aplicación use tipos de ASP.NET Core necesarios para hospedar un servidor.

Puede agregar un servidor gRPC a proyectos que no son de ASP.NET Core con la siguiente configuración del archivo de proyecto:

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

El archivo del proyecto anterior:

  • No usa Microsoft.NET.SDK.Web como el SDK.
  • Agrega una referencia de marco a Microsoft.AspNetCore.App.
    • La referencia de marco permite a aplicaciones no ASP.NET Core, como servicios de Windows, aplicaciones WPF o aplicaciones WinForms, usar API ASP.NET Core.
    • La aplicación ahora puede usar API de ASP.NET Core para iniciar un servidor de ASP.NET Core.
  • Agrega requisitos de gRPC:

Para obtener más información sobre cómo agregar la referencia del marco de Microsoft.AspNetCore.App, vea Uso del marco compartido de ASP.NET Core.

Integración con las API de ASP.NET Core

Los servicios gRPC tienen acceso total a las características de ASP.NET Core, como la inserción de dependencias (ID) y los registros. 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:

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

Resolución de HttpContext en métodos gRPC

La API de gRPC proporciona acceso a algunos datos de mensajes HTTP/2, como el método, el host, el encabezado y los finalizadores. El acceso se realiza a través del argumento ServerCallContext que se pasa a cada método 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 no proporciona acceso completo a HttpContext en todas las API de ASP.NET. 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:

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 adicionales

En este documento se muestra cómo empezar a usar servicios gRPC con ASP.NET Core.

Requisitos previos

Introducción al servicio gRPC en ASP.NET Core

Vea o descargue el código de ejemplo (cómo descargarlo).

Consulte el artículo Introducción a los servicios gRPC para obtener instrucciones detalladas sobre cómo crear un proyecto gRPC.

Incorporación de servicios gRPC a una aplicación de ASP.NET Core

gRPC requiere el paquete Grpc.AspNetCore.

Configuración de gRPC

En Startup.cs:

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

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.

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. Los controladores de solicitudes adicionales, como los controladores MVC, trabajan en paralelo con los servicios gRPC configurados.

Opciones de servidor

Los servicios gRPC se pueden hospedar por todos los servidores de ASP.NET Core integrados.

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

†Requiere .NET 5 y Windows 11, compilación 22000, o Windows Server 2022, compilación 20348 o posterior.

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.

Kestrel

Kestrel es un servidor web multiplataforma de ASP.NET Core. Kestrel se centra en el rendimiento y uso de memoria elevados, pero carece de algunas de las características avanzadas de HTTP.sys como el uso compartido de puertos.

Puntos de conexión gRPC de Kestrel:

HTTP/2

gRPC requiere HTTP/2. gRPC para ASP.NET Core valida que HttpRequest.Protocol sea HTTP/2.

Kestreladmite HTTP/2 en la mayoría de los sistemas operativos modernos. Los puntos de conexión de Kestrel se configuran para admitir conexiones HTTP/1.1 y HTTP/2 de forma predeterminada.

TLS

Los puntos de conexión de Kestrel usados para gRPC deben protegerse con 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. No se requiere ninguna configuración. Un prefijo https comprueba que el punto de conexión de Kestrel está usando TLS.

En un entorno de producción, se debe configurar TLS explícitamente. En el siguiente ejemplo de appsettings.json , se proporciona un punto de conexión HTTP/2 protegido con TLS:

{
  "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:

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

Para más información sobre cómo habilitar TLS con Kestrel, vea Configuración de los puntos de conexión HTTPS para Kestrel.

Negociación del protocolo

TLS no solo se usa para proteger la comunicación. 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. Esta negociación determina si la conexión usa HTTP/1.1 o 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. No se puede usar un punto de conexión con varios protocolos (por ejemplo, HttpProtocols.Http1AndHttp2) sin TLS, porque no hay ninguna negociación. 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.

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.

Nota

macOS no admite gRPC de ASP.NET Core con TLS anterior a .NET 8. Se requiere configuración adicional para ejecutar correctamente servicios gRPC en macOS cuando se usa .NET 7 o anterior. Para obtener más información, vea No se puede iniciar la aplicación gRPC de ASP.NET Core en macOS.

IIS

Internet Information Services (IIS) es un servidor web flexible, seguro y administrable para el hospedaje de aplicaciones web, incluido ASP.NET Core. Se requiere .NET 5 y Windows 11 en compilación 22000 o Windows Server 2022 en compilación 20348 o posterior para hospedar servicios gRPC con IIS.

IIS debe estar configurado para usar TLS y HTTP/2. Para obtener más información, vea Uso de ASP.NET Core con HTTP/2 en IIS.

HTTP.sys

HTTP.sys es un servidor web de ASP.NET Core que solo se ejecuta en Windows. Se requiere .NET 5 y Windows 11 en compilación 22000 o Windows Server 2022 en compilación 20348 o posterior para hospedar servicios gRPC con HTTP.sys.

HTTP.sys debe estar configurado para usar TLS y HTTP/2. Para obtener más información, vea Compatibilidad con HTTP/2 del servidor web HTTP.sys.

Hospedaje de gRPC en proyectos que no son de ASP.NET Core

Normalmente, un servidor gRPC de ASP.NET Core se crea a partir de la plantilla de gRPC. El archivo de proyecto creado por la plantilla usa Microsoft.NET.SDK.Web como 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>

El valor del SDK Microsoft.NET.SDK.Web agrega automáticamente una referencia al marco ASP.NET Core. La referencia permite que la aplicación use tipos de ASP.NET Core necesarios para hospedar un servidor.

Puede agregar un servidor gRPC a proyectos que no son de ASP.NET Core con la siguiente configuración del archivo de proyecto:

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

El archivo del proyecto anterior:

  • No usa Microsoft.NET.SDK.Web como el SDK.
  • Agrega una referencia de marco a Microsoft.AspNetCore.App.
    • La referencia de marco permite a aplicaciones no ASP.NET Core, como servicios de Windows, aplicaciones WPF o aplicaciones WinForms, usar API ASP.NET Core.
    • La aplicación ahora puede usar API de ASP.NET Core para iniciar un servidor de ASP.NET Core.
  • Agrega requisitos de gRPC:

Para obtener más información sobre cómo agregar la referencia del marco de Microsoft.AspNetCore.App, vea Uso del marco compartido de ASP.NET Core.

Integración con las API de ASP.NET Core

Los servicios gRPC tienen acceso total a las características de ASP.NET Core, como la inserción de dependencias (ID) y los registros. 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:

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

Resolución de HttpContext en métodos gRPC

La API de gRPC proporciona acceso a algunos datos de mensajes HTTP/2, como el método, el host, el encabezado y los finalizadores. El acceso se realiza a través del argumento ServerCallContext que se pasa a cada método 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 no proporciona acceso completo a HttpContext en todas las API de ASP.NET. 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:

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 adicionales

En este documento se muestra cómo empezar a usar servicios gRPC con ASP.NET Core.

Requisitos previos

Introducción al servicio gRPC en ASP.NET Core

Vea o descargue el código de ejemplo (cómo descargarlo).

Consulte el artículo Introducción a los servicios gRPC para obtener instrucciones detalladas sobre cómo crear un proyecto gRPC.

Incorporación de servicios gRPC a una aplicación de ASP.NET Core

gRPC requiere el paquete Grpc.AspNetCore.

Configuración de gRPC

En Startup.cs:

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

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.

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. Los controladores de solicitudes adicionales, como los controladores MVC, trabajan en paralelo con los servicios gRPC configurados.

Opciones de servidor

Los servicios gRPC se pueden hospedar por todos los servidores de ASP.NET Core integrados.

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

†Requiere .NET 5 y Windows 11, compilación 22000, o Windows Server 2022, compilación 20348 o posterior.

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.

Kestrel

Kestrel es un servidor web multiplataforma de ASP.NET Core. Kestrel se centra en el rendimiento y uso de memoria elevados, pero carece de algunas de las características avanzadas de HTTP.sys como el uso compartido de puertos.

Puntos de conexión gRPC de Kestrel:

HTTP/2

gRPC requiere HTTP/2. gRPC para ASP.NET Core valida que HttpRequest.Protocol sea HTTP/2.

Kestreladmite HTTP/2 en la mayoría de los sistemas operativos modernos. Los puntos de conexión de Kestrel se configuran para admitir conexiones HTTP/1.1 y HTTP/2 de forma predeterminada.

TLS

Los puntos de conexión de Kestrel usados para gRPC deben protegerse con 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. No se requiere ninguna configuración. Un prefijo https comprueba que el punto de conexión de Kestrel está usando TLS.

En un entorno de producción, se debe configurar TLS explícitamente. En el siguiente ejemplo de appsettings.json , se proporciona un punto de conexión HTTP/2 protegido con TLS:

{
  "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:

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

Para más información sobre cómo habilitar TLS con Kestrel, vea Configuración de los puntos de conexión HTTPS para Kestrel.

Negociación del protocolo

TLS no solo se usa para proteger la comunicación. 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. Esta negociación determina si la conexión usa HTTP/1.1 o 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. No se puede usar un punto de conexión con varios protocolos (por ejemplo, HttpProtocols.Http1AndHttp2) sin TLS, porque no hay ninguna negociación. 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.

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.

Nota

macOS no admite gRPC de ASP.NET Core con TLS anterior a .NET 8. Se requiere configuración adicional para ejecutar correctamente servicios gRPC en macOS cuando se usa .NET 7 o anterior. Para obtener más información, vea No se puede iniciar la aplicación gRPC de ASP.NET Core en macOS.

Hospedaje de gRPC en proyectos que no son de ASP.NET Core

Normalmente, un servidor gRPC de ASP.NET Core se crea a partir de la plantilla de gRPC. El archivo de proyecto creado por la plantilla usa Microsoft.NET.SDK.Web como 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>

El valor del SDK Microsoft.NET.SDK.Web agrega automáticamente una referencia al marco ASP.NET Core. La referencia permite que la aplicación use tipos de ASP.NET Core necesarios para hospedar un servidor.

Puede agregar un servidor gRPC a proyectos que no son de ASP.NET Core con la siguiente configuración del archivo de proyecto:

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

El archivo del proyecto anterior:

  • No usa Microsoft.NET.SDK.Web como el SDK.
  • Agrega una referencia de marco a Microsoft.AspNetCore.App.
    • La referencia de marco permite a aplicaciones no ASP.NET Core, como servicios de Windows, aplicaciones WPF o aplicaciones WinForms, usar API ASP.NET Core.
    • La aplicación ahora puede usar API de ASP.NET Core para iniciar un servidor de ASP.NET Core.
  • Agrega requisitos de gRPC:

Para obtener más información sobre cómo agregar la referencia del marco de Microsoft.AspNetCore.App, vea Uso del marco compartido de ASP.NET Core.

Integración con las API de ASP.NET Core

Los servicios gRPC tienen acceso total a las características de ASP.NET Core, como la inserción de dependencias (ID) y los registros. 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:

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

Resolución de HttpContext en métodos gRPC

La API de gRPC proporciona acceso a algunos datos de mensajes HTTP/2, como el método, el host, el encabezado y los finalizadores. El acceso se realiza a través del argumento ServerCallContext que se pasa a cada método 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 no proporciona acceso completo a HttpContext en todas las API de ASP.NET. 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:

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 adicionales

En este documento se muestra cómo empezar a usar servicios gRPC con ASP.NET Core.

Requisitos previos

Introducción al servicio gRPC en ASP.NET Core

Vea o descargue el código de ejemplo (cómo descargarlo).

Consulte el artículo Introducción a los servicios gRPC para obtener instrucciones detalladas sobre cómo crear un proyecto gRPC.

Incorporación de servicios gRPC a una aplicación de ASP.NET Core

gRPC requiere el paquete Grpc.AspNetCore.

Configuración de gRPC

En Startup.cs:

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

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.

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. Los controladores de solicitudes adicionales, como los controladores MVC, trabajan en paralelo con los servicios gRPC configurados.

Opciones de servidor

Los servicios gRPC se pueden hospedar por todos los servidores de ASP.NET Core integrados.

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

†Requiere .NET 5 y Windows 11, compilación 22000, o Windows Server 2022, compilación 20348 o posterior.

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.

Kestrel

Kestrel es un servidor web multiplataforma de ASP.NET Core. Kestrel se centra en el rendimiento y uso de memoria elevados, pero carece de algunas de las características avanzadas de HTTP.sys como el uso compartido de puertos.

Puntos de conexión gRPC de Kestrel:

HTTP/2

gRPC requiere HTTP/2. gRPC para ASP.NET Core valida que HttpRequest.Protocol sea HTTP/2.

Kestreladmite HTTP/2 en la mayoría de los sistemas operativos modernos. Los puntos de conexión de Kestrel se configuran para admitir conexiones HTTP/1.1 y HTTP/2 de forma predeterminada.

TLS

Los puntos de conexión de Kestrel usados para gRPC deben protegerse con 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. No se requiere ninguna configuración. Un prefijo https comprueba que el punto de conexión de Kestrel está usando TLS.

En un entorno de producción, se debe configurar TLS explícitamente. En el siguiente ejemplo de appsettings.json , se proporciona un punto de conexión HTTP/2 protegido con TLS:

{
  "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:

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

Para más información sobre cómo habilitar TLS con Kestrel, vea Configuración de los puntos de conexión HTTPS para Kestrel.

Negociación del protocolo

TLS no solo se usa para proteger la comunicación. 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. Esta negociación determina si la conexión usa HTTP/1.1 o 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. No se puede usar un punto de conexión con varios protocolos (por ejemplo, HttpProtocols.Http1AndHttp2) sin TLS, porque no hay ninguna negociación. 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.

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.

Nota

macOS no admite gRPC de ASP.NET Core con TLS anterior a .NET 8. Se requiere configuración adicional para ejecutar correctamente servicios gRPC en macOS cuando se usa .NET 7 o anterior. Para obtener más información, vea No se puede iniciar la aplicación gRPC de ASP.NET Core en macOS.

Hospedaje de gRPC en proyectos que no son de ASP.NET Core

Normalmente, un servidor gRPC de ASP.NET Core se crea a partir de la plantilla de gRPC. El archivo de proyecto creado por la plantilla usa Microsoft.NET.SDK.Web como 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>

El valor del SDK Microsoft.NET.SDK.Web agrega automáticamente una referencia al marco ASP.NET Core. La referencia permite que la aplicación use tipos de ASP.NET Core necesarios para hospedar un servidor.

Puede agregar un servidor gRPC a proyectos que no son de ASP.NET Core con la siguiente configuración del archivo de proyecto:

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

El archivo del proyecto anterior:

  • No usa Microsoft.NET.SDK.Web como el SDK.
  • Agrega una referencia de marco a Microsoft.AspNetCore.App.
    • La referencia de marco permite a aplicaciones no ASP.NET Core, como servicios de Windows, aplicaciones WPF o aplicaciones WinForms, usar API ASP.NET Core.
    • La aplicación ahora puede usar API de ASP.NET Core para iniciar un servidor de ASP.NET Core.
  • Agrega requisitos de gRPC:

Para obtener más información sobre cómo agregar la referencia del marco de Microsoft.AspNetCore.App, vea Uso del marco compartido de ASP.NET Core.

Integración con las API de ASP.NET Core

Los servicios gRPC tienen acceso total a las características de ASP.NET Core, como la inserción de dependencias (ID) y los registros. 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:

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

Resolución de HttpContext en métodos gRPC

La API de gRPC proporciona acceso a algunos datos de mensajes HTTP/2, como el método, el host, el encabezado y los finalizadores. El acceso se realiza a través del argumento ServerCallContext que se pasa a cada método 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 no proporciona acceso completo a HttpContext en todas las API de ASP.NET. 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:

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 adicionales