Serviços do gRPC com o ASP.NET Core

Este documento mostra como começar a usar serviços gRPC usando o ASP.NET Core.

Pré-requisitos

Visual Studio

• Visual Studio 2022 com a carga de trabalho de desenvolvimento Web e do ASP.NET.

  

Visual Studio Code

• Visual Studio Code
• C# para Visual Studio Code (versão mais recente)
• SDK DO .NET 8.0

As instruções do Visual Studio Code usam a CLI do .NET para funções de desenvolvimento do ASP.NET Core, como criação de projeto. Você pode seguir estas instruções no macOS, no Linux ou no Windows e com qualquer editor de código. Alterações secundárias poderão ser necessárias se você usar algo diferente do Visual Studio Code.

Visual Studio para Mac

• Visual Studio 2022 para Mac (versão mais recente)

  Importante

  A Microsoft anunciou a desativação do Visual Studio para Mac. O Visual Studio para Mac não terá mais suporte a partir de 31 de agosto de 2024. As alternativas incluem:

  • Visual Studio Code com o Kit de Desenvolvimento do C# e extensões relacionadas, como .NET MAUI e Unity.
  • IDE do Visual Studio em execução no Windows em uma VM no Mac.
  • DE do Visual Studio em execução no Windows em uma VM na Nuvem.

  Para obter mais informações, confira o comunicado de desativação do Visual Studio para Mac.

Introdução ao serviço de gRPC no ASP.NET Core

Exibir ou baixar um código de exemplo (como baixar).

Visual Studio

Confira a Introdução aos serviços gRPC para obter instruções detalhadas sobre como criar um projeto gRPC.

Visual Studio Code/Visual Studio para Mac

Da linha de comando, execute dotnet new grpc -o GrpcGreeter.

Adicionar serviços gRPC a um aplicativo ASP.NET Core

O gRPC requer o pacote Grpc.AspNetCore.

Configurar o gRPC

Em Program.cs:

• O gRPC está habilitado com o método AddGrpc.
• Cada serviço gRPC é adicionado ao pipeline de roteamento por meio do 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();

Se você quiser ver os comentários de código traduzidos para idiomas diferentes do inglês, informe-nos neste problema de discussão do GitHub.

O middleware e recursos do ASP.NET Core compartilham o pipeline de roteamento, portanto, um aplicativo pode ser configurado para atender a manipuladores de solicitação adicionais. Os manipuladores de solicitação adicionais, como controladores MVC, funcionam em paralelo com os serviços gRPC configurados.

Opções de servidor

Os serviços gRPC podem ser hospedados por todos os servidores ASP.NET Core internos.

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

†Requer .NET 5 e Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou posterior.

Para obter mais informações sobre como escolher o servidor certo para um aplicativo ASP.NET Core, confira Implementações de servidor Web em ASP.NET Core.

Kestrel

O Kestrel é um servidor Web multiplataforma para ASP.NET Core. O Kestrel se concentra em alto desempenho e utilização de memória, mas não tem alguns dos recursos avançados no HTTP.sysm como compartilhamento de porta.

Pontos de extremidade gRPC do Kestrel:

• Exigir HTTP/2.
• Deve ser protegido com TLS (Transport Layer Security).

HTTP/2

gRPC requer HTTP/2. O gRPC para ASP.NET Core valida HttpRequest.Protocol que é HTTP/2.

O Kestreldá suporte a HTTP/2 na maioria dos sistemas operacionais modernos. Os ponto de extremidade Kestrel são configurados para dar suporte a conexões HTTP/1.1 e HTTP/2 por padrão.

TLS

Os pontos de extremidade Kestrel usados para gRPC devem ser protegidos com TLS. No desenvolvimento, um ponto de extremidade protegido com TLS é criado automaticamente em https://localhost:5001 quando o certificado de desenvolvimento ASP.NET Core está presente. Nenhuma configuração é necessária. Um prefixo https verifica se o ponto de extremidade Kestrel está usando TLS.

Em produção, o TLS precisa ser configurado explicitamente. No exemplo appsettings.json a seguir, um ponto de extremidade HTTP/2 protegido com TLS é fornecido:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Como alternativa, os pontos de extremidade Kestrel podem ser configurados em 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 obter mais informações sobre como habilitar o TLS com o Kestrel, confira Configuração do ponto de extremidade HTTPS do Kestrel.

Negociação de protocolo

O TLS é usado para mais do que proteger a comunicação. O handshake APLN (Negociação de Protocolo de Camada de Aplicativo) TLS é usado para negociar o protocolo de conexão entre o cliente e o servidor quando um ponto de extremidade dá suporte a vários protocolos. Essa negociação determina se a conexão usa HTTP/1.1 ou HTTP/2.

Se um ponto de extremidade HTTP/2 for configurado sem TLS, os ListenOptions.Protocols do ponto de extremidade precisarão ser definidos como HttpProtocols.Http2. Um ponto de extremidade com vários protocolos, como HttpProtocols.Http1AndHttp2 por exemplo, não pode ser usado sem TLS porque não há negociação. Todas as conexões com o ponto de extremidade sem segurança padrão para HTTP/1.1 e chamadas gRPC falham.

Para obter mais informações sobre como habilitar HTTP/2 e TLS com o Kestrel, confira a configuração do ponto de extremidadeKestrel.

Observação

O macOS não dá suporte ao gRPC do ASP.NET Core com TLS anterior ao .NET 8. É necessária uma configuração adicional para executar com êxito os serviços gRPC no macOS ao usar o .NET 7 ou anterior. Para obter mais informações, confira Não é possível iniciar o aplicativo ASP.NET Core gRPC no macOS.

IIS

O ISS (Serviços de Informações da Internet) é um Servidor Web flexível, seguro e gerenciável para hospedar aplicativos Web, incluindo o ASP.NET Core. .NET 5, Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou posterior são necessários para hospedar serviços de gRPC com IIS.

O IIS deve ser configurado para usar TLS e HTTP/2. Para obter mais informações, confira Usar o ASP.NET Core com HTTP/2 no IIS.

HTTP.sys

O HTTP.sys é um servidor Web para ASP.NET Core executado apenas no Windows. .NET 5, Windows 11 Build 22000 ou Windows Server 2022 Build 20348 ou posterior são necessários para hospedar serviços de gRPC com HTTP.sys.

O HTTP.sys deve ser configurado para usar TLS e HTTP/2. Para obter mais informações, confira Suporte a HTTP.sys do servidor Web HTTP/2.

Hospedar gRPC em projetos que não são do ASP.NET Core

Um servidor gRPC do ASP.NET Core geralmente é criado a partir do modelo gRPC. O arquivo de projeto criado pelo modelo usa o Microsoft.NET.SDK.Web como o 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>

O valor do SDK Microsoft.NET.SDK.Web adiciona automaticamente uma referência à estrutura do ASP.NET Core. A referência permite que o aplicativo use os tipos ASP.NET Core necessários para hospedar um servidor.

Você pode adicionar um servidor gRPC a projetos que não são do ASP.NET Core com as seguintes configurações de arquivo de projeto:

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

O arquivo de projeto anterior:

• Não usa Microsoft.NET.SDK.Web como o SDK.
• Adiciona uma referência de estrutura a Microsoft.AspNetCore.App.
  • A referência de estrutura permite que os aplicativos não ASP.NET Core, como os serviços Windows, aplicativos WPF ou aplicativos WinForms, usem APIs do ASP.NET Core.
  • Agora, o aplicativo pode usar APIs do ASP.NET Core para iniciar um servidor ASP.NET Core.
• Adiciona requisitos de gRPC:
  • Referência do pacote NuGet a Grpc.AspNetCore.
  • arquivo .proto.

Para obter mais informações sobre como usar referência da estrutura Microsoft.AspNetCore.App consulte Como usar a estrutura compartilhada do ASP.NET Core.

Integração com as APIs do ASP.NET Core

Os serviços gRPC têm acesso total aos recursos do ASP.NET Core, como DI (Injeção de Dependência) e Registro em log. Por exemplo, a implementação do serviço pode resolve um serviço de agente do contêiner de DI por meio do construtor:

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

Por padrão, a implementação do serviço gRPC pode resolver outros serviços de DI com qualquer tempo de vida (Singleton, Escopo ou Transitório).

Resolver HttpContext em métodos gRPC

A API do gRPC fornece acesso a alguns dados de mensagem HTTP/2, como o método, host, cabeçalho e trailers. O acesso é por meio do argumento ServerCallContext passado para 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
        });
    }
}

O ServerCallContext não fornece acesso completo a HttpContext em todas as APIs do ASP.NET. O método de extensão GetHttpContext fornece acesso completo ao HttpContext, que representa a mensagem HTTP/2 subjacente nas APIs do 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 adicionais

• Criar um cliente e um servidor gRPC do .NET Core no ASP.NET Core
• Visão geral do gRPC no .NET
• Serviços do gRPC com C#
• Servidor web Kestrel no ASP.NET Core