Tutorial: Crear un servidor y un cliente gRPC en ASP.NET Core

Por John Luo

En este tutorial se muestra cómo crear un cliente gRPC de .NET Core y un servidor gRPC de ASP.NET Core.

Al final tendrá un cliente gRPC que se comunica con el servicio Greeter de gRPC.

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

En este tutorial ha:

  • Crear un servicio gRPC.
  • Crear un cliente gRPC.
  • Probar el servicio cliente gRPC con el servicio gRPC Greeter.

Requisitos previos

Crear un servicio gRPC

  • Inicie Visual Studio y seleccione Crear un proyecto. Alternativamente, en el menú Archivo de Visual Studio, seleccione Nuevo > Proyecto.

  • En el cuadro de diálogo Crear un proyecto, seleccione Servicio gRPC y elija Siguiente:

    Creación de un cuadro de diálogo de nuevo proyecto en Visual Studio

  • Llame al proyecto GrpcGreeter. Es importante asignarle el nombre GrpcGreeter para que los espacios de nombres coincidan al copiar y pegar el código.

  • Seleccione Crear.

  • En el cuadro de diálogo Crear un servicio gRPC:

    • Se selecciona la plantilla Servicio gRPC.
    • Seleccione Crear.

Ejecutar el servicio

  • Presione Ctrl+F5 para ejecutarla sin el depurador.

    Visual Studio muestra el cuadro de diálogo siguiente:

    Este proyecto está configurado para usar SSL. Para evitar advertencias de SSL en el explorador, puede elegir confiar en el certificado autofirmado que ha generado IIS Express. ¿Quiere confiar en el certificado SSL de IIS Express?

    Haga clic en si confía en el certificado SSL de IIS Express.

    Se muestra el cuadro de diálogo siguiente:

    Cuadro de diálogo de advertencia de seguridad

    Si acepta confiar en el certificado de desarrollo, seleccione .

    Para obtener información sobre cómo confiar en el explorador Firefox, consulte Error de certificado SEC_ERROR_INADEQUATE_KEY_USAGE de Firefox.

    Visual Studio inicia IIS Express y ejecuta la aplicación. En la barra de direcciones aparece localhost:port# (y no algo como example.com). Esto es así porque localhost es el nombre de host estándar del equipo local. Localhost solo sirve las solicitudes web del equipo local. Cuando Visual Studio crea un proyecto web, se usa un puerto aleatorio para el servidor web.

Los registros muestran que el servicio está escuchando en https://localhost:5001.

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

Nota

La plantilla gRPC está configurada para usar Seguridad de la capa de transporte (TLS). Los clientes de gRPC necesitan usar HTTPS para llamar al servidor.

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

Examen de los archivo del proyecto

Archivos de proyecto de GrpcGreeter:

  • greet.proto: El archivo Protos/greet.proto define el gRPC Greeter y se usa para generar los recursos de servidor gRPC. Para obtener más información, vea Introducción a gRPC.
  • Carpeta Servicios: contiene la implementación del servicio Greeter.
  • appSettings.json: contiene datos de configuración, como el protocolo que usa Kestrel. Para obtener más información, vea Configuración en ASP.NET Core.
  • Program.cs: contiene el punto de entrada para el servicio gRPC. Para obtener más información, vea Host genérico de .NET en ASP.NET Core.
  • Startup.cs: Contiene código que configura el comportamiento de la aplicación. Para obtener más información, vea Inicio de la aplicación.

Creación del cliente gRPC en una aplicación de consola de .NET

  • Abra una segunda instancia de Visual Studio y seleccione Crear un proyecto.
  • En el cuadro de diálogo Crear un proyecto, seleccione Aplicación de consola (.NET Core) y elija Siguiente.
  • En el cuadro de texto Nombre de proyecto, escriba GrpcGreeterClient y seleccione Crear.

Adición de paquetes necesarios

El proyecto de cliente gRPC requiere los siguientes paquetes:

  • Grpc.Net.Client, que contiene el cliente de .NET Core.
  • Google.Protobuf, que contiene API de mensajes protobuf para C#.
  • Grpc.Tools, que contiene compatibilidad con herramientas de C# para archivos protobuf. El paquete de herramientas no es necesario en el runtime, de modo que la dependencia se marca con PrivateAssets="All".

Instale los paquetes con la Consola del Administrador de paquetes (PMC) o mediante Administrar paquetes NuGet.

Opción de PMC para instalar paquetes

  • En Visual Studio, seleccione Herramientas > Administrador de paquetes de NuGet > Consola del Administrador de paquetes.

  • En la ventana Consola del Administrador de paquetes, ejecute cd GrpcGreeterClient para cambiar los directorios a la carpeta que contiene los archivos GrpcGreeterClient.csproj.

  • Ejecute los comandos siguientes:

    Install-Package Grpc.Net.Client
    Install-Package Google.Protobuf
    Install-Package Grpc.Tools
    

Administración de la opción Paquetes NuGet para instalar paquetes

  • Haga clic con el botón derecho en el proyecto en el Explorador de soluciones > Administrar paquetes NuGet.
  • Seleccione la pestaña Examinar.
  • Escriba Grpc.Net.Client en el cuadro de búsqueda.
  • Seleccione el paquete Grpc.Net.Client en la pestaña Examinar y haga clic en Instalar.
  • Repita el proceso para Google.Protobuf y Grpc.Tools.

Adición de greet.proto

  • Cree una carpeta Protos en el proyecto de cliente gRPC.

  • Copie el archivo Protos\greet.proto del servicio gRPC Greeter en el proyecto de cliente gRPC.

  • Actualice el espacio de nombres del archivo greet.proto al espacio de nombres del proyecto:

    option csharp_namespace = "GrpcGreeterClient";
    
  • Edite el archivo de proyecto GrpcGreeterClient.csproj:

    Haga clic con el botón derecho en el proyecto y seleccione Editar archivo del proyecto.


  • Agregue un grupo de elementos con un elemento <Protobuf> que hace referencia al archivo greet.proto:

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

Creación del cliente de Greeter

Compile el proyecto de cliente para crear los tipos en el espacio de nombres GrpcGreeter. El proceso de compilación genera automáticamente los tipos GrpcGreeter.

Actualice el archivo Program.cs del cliente gRPC con el código siguiente:

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Grpc.Net.Client;

namespace GrpcGreeterClient
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // The port number(5001) must match the port of the gRPC server.
            using var channel = GrpcChannel.ForAddress("https://localhost:5001");
            var client =  new Greeter.GreeterClient(channel);
            var reply = await client.SayHelloAsync(
                              new HelloRequest { Name = "GreeterClient" });
            Console.WriteLine("Greeting: " + reply.Message);
            Console.WriteLine("Press any key to exit...");
            Console.ReadKey();
        }
    }
}

Program.cs contiene el punto de entrada y la lógica para el cliente gRPC.

El cliente de Greeter se crea mediante lo siguiente:

  • Creación de una instancia de GrpcChannel que contiene la información para crear la conexión al servicio gRPC.
  • Uso de GrpcChannel para construir el cliente de Greeter:
static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    var client =  new Greeter.GreeterClient(channel);
    var reply = await client.SayHelloAsync(
                      new HelloRequest { Name = "GreeterClient" });
    Console.WriteLine("Greeting: " + reply.Message);
    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

El cliente de Greeter realiza una llamada al método SayHello asincrónico. Se muestra el resultado de la llamada a SayHello:

static async Task Main(string[] args)
{
    // The port number(5001) must match the port of the gRPC server.
    using var channel = GrpcChannel.ForAddress("https://localhost:5001");
    var client =  new Greeter.GreeterClient(channel);
    var reply = await client.SayHelloAsync(
                      new HelloRequest { Name = "GreeterClient" });
    Console.WriteLine("Greeting: " + reply.Message);
    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

Prueba del cliente gRPC con el servicio gRPC Greeter

  • En el servicio Greeter, presione Ctrl+F5 para iniciar el servidor sin el depurador.
  • En el proyecto GrpcGreeterClient, presione Ctrl+F5 para iniciar el cliente sin el depurador.

El cliente envía un saludo al servicio con un mensaje que contiene su nombre GreeterClient. El servicio envía el mensaje "Hello GreeterClient" como respuesta. La respuesta "Hello GreeterClient" se muestra en el símbolo del sistema:

Greeting: Hello GreeterClient
Press any key to exit...

El servicio gRPC registra los detalles de la llamada correcta en los registros escritos en el símbolo del sistema:

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
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\GH\aspnet\docs\4\Docs\aspnetcore\tutorials\grpc\grpc-start\sample\GrpcGreeter
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 POST https://localhost:5001/Greet.Greeter/SayHello application/grpc
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /Greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /Greet.Greeter/SayHello'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 78.32260000000001ms 200 application/grpc

Nota

El código de este artículo requiere el certificado de desarrollo de .NET Core HTTPS para proteger el servicio gRPC. Si el cliente gRPC de .NET genera un error con el mensaje The remote certificate is invalid according to the validation procedure. o The SSL connection could not be established., el certificado de desarrollo no es de confianza. Para corregir este problema, consulte Llamada a un servicio gRPC con un certificado no válido o que no es de confianza.

Advertencia

ASP.NET Core gRPC tiene requisitos adicionales para su uso con Azure App Service o IIS. Para obtener más información sobre dónde se puede usar gRPC, vea gRPC en plataformas compatibles con .NET.

Pasos siguientes