Serviços gRPC com ASP.NET Core

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

Prerequisites

Estúdio Visual

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

  

• de código do Visual Studio
• C# para Visual Studio Code (versão mais recente)
• SDK do .NET 8

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

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

Ver ou descarregar o código de exemplo (como fazer o download).

Estúdio Visual

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

Execute dotnet new grpc -o GrpcGreeter a partir da linha de comando.

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

gRPC requer o Grpc.AspNetCore pacote.

Configurar gRPC

Em Program.cs:

• gRPC é ativado 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ê gostaria de ver os comentários de código traduzidos para outros idiomas além do inglês, informe-nos em este problema de discussão do GitHub.

ASP.NET middleware e os recursos principais compartilham o pipeline de roteamento, portanto, um aplicativo pode ser configurado para atender 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 do servidor

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

• 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, consulte implementações de servidor Web no ASP.NET Core.

Kestrel

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

Kestrel pontos finais gRPC:

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

HTTP/2

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

Kestrel suporta HTTP/2 na maioria dos sistemas operacionais modernos. Kestrel pontos de extremidade são configurados para suportar conexões HTTP/1.1 e HTTP/2 por padrão.

TLS

Kestrel endpoints utilizados para gRPC devem ser protegidos com TLS. No desenvolvimento, um endpoint 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 que o ponto de extremidade Kestrel está usando TLS.

Na produção, o TLS deve ser explicitamente configurado. No exemplo seguinte appsettings.json, é apresentado um ponto de extremidade HTTP/2 protegido com TLS:

{
  "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 Kestrel, consulte Kestrelde configuração do ponto de extremidade HTTPS.

Negociação de protocolos

O TLS é usado para mais do que proteger a comunicação. A negociação do protocolo TLS Application-Layer (ALPN) através do aperto de mão é utilizada para acertar o protocolo de conexão entre o cliente e o servidor quando um ponto de extremidade suporta 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 estiver configurado sem TLS, os ListenOptions.Protocols do ponto de extremidade deverã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 ligações para o endpoint não seguro usam por padrão HTTP/1.1, e as chamadas gRPC falham.

Para obter mais informações sobre como habilitar HTTP/2 e TLS com Kestrel, consulte Kestrel endpoint configuration.

Note

O macOS não suporta ASP.NET Core gRPC com TLS antes do .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, consulte Não é possível iniciar aplicativo gRPC do ASP.NET Core no macOS.

IIS

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

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

HTTP.sys

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

HTTP.sys deve ser configurado para usar TLS e HTTP/2. Para obter mais informações, consulte o suporte HTTP/2 do servidor Web HTTP.sys.

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

Um servidor gRPC ASP.NET Core normalmente é criado a partir do modelo gRPC. O arquivo de projeto criado pelo modelo usa 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 Microsoft.NET.SDK.Web SDK adiciona automaticamente uma referência à estrutura ASP.NET Core. A referência permite que o aplicativo use ASP.NET tipos Core necessários para hospedar um servidor.

Você pode adicionar um servidor gRPC a non-ASP.NET projetos principais 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 SDK.
• Adiciona uma referência de estrutura a Microsoft.AspNetCore.App.
  • A referência de estrutura permite que aplicativos non-ASP.NET Core, como Serviços do Windows, aplicativos WPF ou aplicativos WinForms, usem APIs ASP.NET Core.
  • O aplicativo agora pode usar APIs ASP.NET Core para iniciar um servidor ASP.NET Core.
• Adiciona requisitos gRPC:
  • Referência do pacote NuGet para Grpc.AspNetCore.
  • .proto arquivo.

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

Integração com APIs ASP.NET Core

Os serviços gRPC têm acesso total aos recursos ASP.NET Core, como de injeção de dependência (DI) e registro em log . Por exemplo, a implementação do serviço pode resolver um serviço de registrador do contêiner DI.

Injeção do construtor:

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;

    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }
}

Injeção do construtor primário (.NET 8 ou posterior):

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

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

Resolver HttpContext em métodos gRPC

A API gRPC fornece acesso a alguns dados de mensagens HTTP/2, como o método, host, cabeçalho e trailers. O acesso é feito através 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
        });
    }
}

ServerCallContext não fornece acesso total a HttpContext em todas as ASP.NET APIs. O método de extensão GetHttpContext fornece acesso total ao HttpContext que representa a mensagem HTTP/2 subjacente em ASP.NET APIs:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Recursos adicionais

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