Solución de problemas de gRPC en .NET

Por James Newton-King

En este documento se describen los problemas que suelen surgir al desarrollar aplicaciones de gRPC en .NET.

Falta de coincidencia entre la configuración de cliente y servicio de SSL/TLS

La plantilla y los ejemplos de gRPC usan Seguridad de la capa de transporte (TLS) de forma predeterminada para proteger los servicios gRPC. Los clientes de gRPC deben usar una conexión segura para llamar correctamente a los servicios gRPC protegidos.

Puede comprobar si el servicio gRPC de ASP.NET Core usa TLS en los registros que se escriben al iniciar la aplicación. El servicio escuchará en un punto de conexión HTTPS:

info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

El cliente de .NET Core debe usar https en la dirección del servidor para realizar llamadas con una conexión segura:

var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = new Greeter.GreeterClient(channel);

Todas las implementaciones de cliente de gRPC admiten TLS. Los clientes de gRPC de otros lenguajes de programación normalmente requieren que el canal esté configurado con SslCredentials. SslCredentials especifica el certificado que usará el cliente, y debe usarse en lugar de credenciales no seguras. Para obtener ejemplos de configuración de las distintas implementaciones de cliente de gRPC para usar TLS, vea Autenticación en gRPC.

Llamada a un servicio gRPC con un certificado no válido o que no es de confianza

El cliente de gRPC de .NET requiere que el servicio tenga un certificado de confianza. Cuando se llama a un servicio gRPC sin un certificado de confianza, se devuelve el siguiente mensaje de error:

Excepción no controlada. System.Net.Http.HttpRequestException: No se ha podido establecer la conexión SSL, vea la excepción interna. ---> System.Security.Authentication.AuthenticationException: el certificado remoto no es válido de acuerdo con el procedimiento de validación.

Puede aparecer este error si está probando la aplicación de forma local y el certificado de desarrollo HTTPS de ASP.NET Core no es de confianza. Para instrucciones sobre cómo corregir este problema, consulte Confiar en el certificado de desarrollo de ASP.NET Core HTTPS en Windows y macOS.

Si está llamando a un servicio gRPC en otro equipo y no puede confiar en el certificado, el cliente de gRPC se puede configurar para que omita el certificado no válido. En el código siguiente se usa HttpClientHandler.ServerCertificateCustomValidationCallback para permitir llamadas sin un certificado de confianza:

var handler = new HttpClientHandler();
handler.ServerCertificateCustomValidationCallback = 
    HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

var channel = GrpcChannel.ForAddress("https://localhost:5001",
    new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

La fábrica cliente gRPC permite llamadas sin un certificado de confianza. Use el método de extensión ConfigurePrimaryHttpMessageHandler para configurar el controlador en el cliente:

var services = new ServiceCollection();

services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
    {
        o.Address = new Uri("https://localhost:5001");
    })
    .ConfigurePrimaryHttpMessageHandler(() =>
    {
        var handler = new HttpClientHandler();
        handler.ServerCertificateCustomValidationCallback =
            HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;

        return handler;
    });

Advertencia

Los certificados que no son de confianza solo se deben usar durante el desarrollo de aplicaciones. Las aplicaciones de producción siempre deben usar certificados válidos.

Llamada a servicios gRPC no seguros con el cliente de .NET Core

El cliente de gRPC de .NET puede llamar a servicios de gRPC no seguros al especificar http en la dirección del servidor. Por ejemplo, GrpcChannel.ForAddress("http://localhost:5000").

Hay algunos requisitos adicionales para llamar a los servicios de gRPC no seguros en función de la versión de .NET que use una aplicación:

• .NET 5 y versiones posteriores requieren la versión 2.32.0 u otra posterior de Grpc.Net.Client.
• .NET Core 3.x requiere una configuración adicional. La aplicación debe establecer el conmutador System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport en true. Para obtener más información, consulte Asp.Net Core 3.x: llamada a servicios gRPC no seguros con el cliente de .NET:

Importante

Los servicios gRPC no seguros deben hospedarse en un puerto solo HTTP/2. Para más información, consulte Negociación de protocolos de ASP.NET Core.

No se puede iniciar la aplicación gRPC de ASP.NET Core en macOS

Kestrel no admite HTTP/2 con TLS en macOS antes de .NET 8. La plantilla y los ejemplos de gRPC de ASP.NET Core usan TLS de forma predeterminada. Al intentar iniciar el servidor de gRPC, verá el siguiente mensaje de error:

No se puede enlazar a https://localhost:5001 en la interfaz de bucle invertido de IPv4: "No se admite HTTP/2 a través de TLS en macOS debido a la falta de compatibilidad con ALPN".

Para solucionar esta incidencia en .NET 7, configure Kestrel y el cliente de gRPC para que use HTTP/2 sin TLS. Esto solo debe realizarse durante el desarrollo. Si no se usa TLS, se enviarán mensajes gRPC sin cifrado. Para obtener más información, consulte Asp.Net Core 7.0: no se puede iniciar la aplicación gRPC de ASP.NET Core en macOS.

Recursos de C# para gRPC no generados a partir de archivos .proto

Para generar código de gRPC de clientes concretos y clases base de servicio es necesario hacer referencia a los archivos y las herramientas de Protobuf desde un proyecto. Debe incluir:

• Los archivos .proto que quiere usar en el grupo de elementos <Protobuf>. El proyecto debe hacer referencia a los archivos .proto importados.
• Una referencia de paquete al paquete de herramientas de gRPC Grpc.Tools.

Para más información sobre la generación de recursos de C# para gRPC, consulte Servicios gRPC con C#.

Una aplicación web de ASP.NET Core que hospeda servicios gRPC solo necesita la clase base de servicio generada:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>

Una aplicación cliente de gRPC que realiza llamadas a gRPC solo necesita el cliente concreto generado:

<ItemGroup>
  <Protobuf Include="Protos\greet.proto" GrpcServices="Client" />
</ItemGroup>

Imposibilidad para los proyectos de WPF de generar recursos de C# para gRPC a partir de archivos .proto

Los proyectos de WPF tienen un problema conocido que impide que la generación de código de gRPC se realice correctamente. Los tipos de gRPC generados en un proyecto de WPF haciendo referencia a Grpc.Tools y a archivos .proto producirán errores de compilación cuando se usen:

Error CS0246: No se ha encontrado el tipo o el nombre del espacio de nombres "MyGrpcServices" (¿falta una directiva "using" o una referencia de ensamblado?).

Para solucionar este problema:

1. Cree un proyecto de biblioteca de clases .NET Core.
2. En el nuevo proyecto, agregue referencias para habilitar la generación de código de C# a partir de archivos .proto:
   • Agregue las siguientes referencias de paquete:
     • Grpc.Tools
     • Grpc.Net.Client
     • Google.Protobuf
   • Agregue archivos .proto al grupo de elementos <Protobuf>.
3. En la aplicación de WPF, agregue una referencia al nuevo proyecto.

La aplicación de WPF puede usar los tipos generados por gRPC a partir del nuevo proyecto de biblioteca de clases.

Llamada a servicios de gRPC hospedados en un subdirectorio

Advertencia

Muchas herramientas de gRPC de terceros no admiten servicios hospedados en subdirectorios. Considere la posibilidad de buscar una manera de hospedar gRPC como directorio raíz.

El componente de ruta de acceso de la dirección de un canal de gRPC se pasa por alto al realizar llamadas gRPC. Por ejemplo, GrpcChannel.ForAddress("https://localhost:5001/ignored_path") no se utilizará ignored_path al enrutar llamadas gRPC del servicio.

Se omite la ruta de acceso de la dirección porque gRPC tiene una estructura de dirección preceptiva normalizada. Una dirección gRPC combina los nombres de paquete, servicio y método: https://localhost:5001/PackageName.ServiceName/MethodName.

Hay algunos escenarios en los que una aplicación necesita incluir una ruta de acceso con llamadas gRPC. Por ejemplo, cuando una aplicación gRPC de ASP.NET Core está hospedada en un directorio de IIS y el directorio debe incluirse en la solicitud. Cuando se requiera una ruta de acceso, se puede agregar a la llamada gRPC mediante el valor de SubdirectoryHandler personalizado especificado a continuación:

public class SubdirectoryHandler : DelegatingHandler
{
    private readonly string _subdirectory;

    public SubdirectoryHandler(HttpMessageHandler innerHandler, string subdirectory)
        : base(innerHandler)
    {
        _subdirectory = subdirectory;
    }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var old = request.RequestUri;

        var url = $"{old.Scheme}://{old.Host}:{old.Port}";
        url += $"{_subdirectory}{request.RequestUri.AbsolutePath}";
        request.RequestUri = new Uri(url, UriKind.Absolute);

        return base.SendAsync(request, cancellationToken);
    }
}

SubdirectoryHandler se usa cuando se crea el canal gRPC.

var handler = new SubdirectoryHandler(new HttpClientHandler(), "/MyApp");

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

var reply = await client.SayHelloAsync(
                  new HelloRequest { Name = "GreeterClient" });

El código anterior:

• Crea un objeto SubdirectoryHandler con la ruta de acceso /MyApp.
• Configura un canal para que use SubdirectoryHandler.
• Llama al servicio gRPC con SayHelloAsync. La llamada gRPC se envía a https://localhost:5001/MyApp/greet.Greeter/SayHello.

Como alternativa, se puede configurar una fábrica de cliente con SubdirectoryHandler mediante AddHttpMessageHandler.

Configuración del cliente gRPC para usar HTTP/3

El cliente gRPC de .NET admite HTTP/3 con .NET 6 o posterior. Si el servidor envía un encabezado de respuesta alt-svc al cliente que indica que el servidor admite HTTP/3, el cliente actualizará automáticamente su conexión a HTTP/3. Para más información, consulte Uso de HTTP/3 con el servidor web Kestrel de ASP.NET Core.

Se puede usar un elemento DelegatingHandler para forzar a un cliente gRPC a usar HTTP/3. Al forzar HTTP/3 se evita la sobrecarga de actualizar la solicitud. Fuerce HTTP/3 con código similar al siguiente:

public class Http3Handler : DelegatingHandler
{
    public Http3Handler() { }
    public Http3Handler(HttpMessageHandler innerHandler) : base(innerHandler) { }

    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        request.Version = HttpVersion.Version30;
        request.VersionPolicy = HttpVersionPolicy.RequestVersionExact;

        return base.SendAsync(request, cancellationToken);
    }
}

Http3Handler se usa cuando se crea el canal gRPC. El código siguiente crea un canal configurado para usar Http3Handler.

var handler = new Http3Handler(new HttpClientHandler());

var channel = GrpcChannel.ForAddress("https://localhost:5001", new GrpcChannelOptions { HttpHandler = handler });
var client = new Greeter.GreeterClient(channel);

var reply = await client.SayHelloAsync(
                  new HelloRequest { Name = "GreeterClient" });

Como alternativa, se puede configurar una fábrica de cliente con Http3Handler mediante AddHttpMessageHandler.

Compilación de gRPC en Alpine Linux

El paquete Grpc.Toolsgenera tipos de .NET a partir de archivos .proto mediante un binario nativo agrupado denominado protoc. Se requieren pasos adicionales para crear aplicaciones gRPC en las plataformas que no son compatibles con los archivos binarios nativos en Grpc.Tools, como Alpine Linux.

Generación de código con antelación

Una solución consiste en generar código con antelación.

1. Mueva los archivos .proto y la referencia del paquete Grpc.Tools a un nuevo proyecto.
2. Publique el proyecto como paquete NuGet y cárguelo en una fuente de NuGet.
3. Actualice la aplicación para hacer referencia al paquete NuGet.

Con los pasos anteriores, la aplicación ya no requiere Grpc.Tools para la creación, ya que el código se genera con antelación.

Personalización de archivos binarios nativos Grpc.Tools

Grpc.Tools admite los archivos binarios nativos personalizados. Esta característica permite que las herramientas de gRPC se ejecuten en entornos que sus archivos binarios nativos agrupados no admiten.

Cree o adquiera archivos binarios nativos protoc y grpc_csharp_plugin, y configure Grpc.Tools para que los use. Establezca las siguientes variables de entorno para configurar archivos binarios:

• PROTOBUF_PROTOC: ruta de acceso completa al compilador de búferes de protocolo
• GRPC_PROTOC_PLUGIN: ruta de acceso completa a grpc_csharp_plugin

Para Alpine Linux, hay paquetes que proporciona la comunidad para el compilador de búferes de protocolo y los complementos gRPC en https://pkgs.alpinelinux.org/.

# Build or install the binaries for your architecture.

# e.g. for Alpine Linux the grpc-plugins package can be used
#  See https://pkgs.alpinelinux.org/package/edge/community/x86_64/grpc-plugins
apk add grpc-plugins  # Alpine Linux specific package installer

# Set environment variables for the built/installed protoc
# and grpc_csharp_plugin binaries
export PROTOBUF_PROTOC=/usr/bin/protoc
export GRPC_PROTOC_PLUGIN=/usr/bin/grpc_csharp_plugin

# When dotnet build runs, the Grpc.Tools NuGet package
# uses the binaries pointed to by the environment variables.
dotnet build

Para más información sobre el uso de Grpc.Tools con arquitecturas no admitidas, consulte la documentación de la integración de versiones de gRPC.