Serviços do gRPC com o ASP.NET CoregRPC services with ASP.NET Core

Este documento mostra como começar a usar os serviços gRPCs usando ASP.NET Core.This document shows how to get started with gRPC services using ASP.NET Core.

Aviso

No momento, não há suporte para o ASP.NET Core gRPC no serviço Azure app ou no IIS.ASP.NET Core gRPC is not currently supported on Azure App Service or IIS. A implementação HTTP/2 de http. sys não dá suporte a cabeçalhos de direita de resposta HTTP dos quais o gRPC se baseia.The HTTP/2 implementation of Http.Sys does not support HTTP response trailing headers which gRPC relies on. Para obter mais informações, consulte este problema do GitHub.For more information, see this GitHub issue.

Pré-requisitosPrerequisites

Introdução ao serviço de gRPC no ASP.NET CoreGet started with gRPC service in ASP.NET Core

Exiba ou baixe o código de exemplo (como baixar).View or download sample code (how to download).

Consulte Introdução aos serviços gRPCs para obter instruções detalhadas sobre como criar um projeto gRPC.See Get started with gRPC services for detailed instructions on how to create a gRPC project.

Adicionar serviços gRPCs a um aplicativo ASP.NET CoreAdd gRPC services to an ASP.NET Core app

gRPC requer o pacote gRPC. AspNetCore .gRPC requires the Grpc.AspNetCore package.

Configurar o gRPCConfigure gRPC

Em Startup.cs:In Startup.cs:

  • gRPC é habilitado com o AddGrpc método.gRPC is enabled with the AddGrpc method.
  • Cada serviço gRPC é adicionado ao pipeline de roteamento por meio do MapGrpcService método.Each gRPC service is added to the routing pipeline through the MapGrpcService method.
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>();
        });
    }
}

Se você quiser ver os comentários de código traduzidos para idiomas diferentes do inglês, informe-nos sobre esse problema de discussão do GitHub.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

ASP.NET Core middleware e recursos compartilham o pipeline de roteamento, portanto um aplicativo pode ser configurado para atender a manipuladores de solicitação adicionais.ASP.NET Core middlewares and features share the routing pipeline, therefore an app can be configured to serve additional request handlers. Os manipuladores de solicitação adicionais, como controladores MVC, funcionam em paralelo com os serviços gRPCs configurados.The additional request handlers, such as MVC controllers, work in parallel with the configured gRPC services.

Configurar o KestrelConfigure Kestrel

Kestrel pontos de extremidade gRPC:Kestrel gRPC endpoints:

HTTP/2HTTP/2

gRPC requer HTTP/2.gRPC requires HTTP/2. gRPC para ASP.NET Core valida HttpRequest. Protocol é HTTP/2 .gRPC for ASP.NET Core validates HttpRequest.Protocol is HTTP/2.

O Kestrel dá suporte a http/2 na maioria dos sistemas operacionais modernos.Kestrel supports HTTP/2 on most modern operating systems. Os pontos de extremidade Kestrel são configurados para dar suporte a conexões HTTP/1.1 e HTTP/2 por padrão.Kestrel endpoints are configured to support HTTP/1.1 and HTTP/2 connections by default.

TLSTLS

Os pontos de extremidade Kestrel usados para gRPC devem ser protegidos com TLS.Kestrel endpoints used for gRPC should be secured with TLS. No desenvolvimento, um ponto de extremidade protegido com TLS é criado automaticamente https://localhost:5001 quando o certificado de desenvolvimento de ASP.NET Core está presente.In development, an endpoint secured with TLS is automatically created at https://localhost:5001 when the ASP.NET Core development certificate is present. Nenhuma configuração é necessária.No configuration is required. Um https prefixo verifica se o ponto de extremidade Kestrel está usando TLS.An https prefix verifies the Kestrel endpoint is using TLS.

Em produção, o TLS deve ser configurado explicitamente.In production, TLS must be explicitly configured. No exemplo a seguir appsettings.js , um ponto de extremidade http/2 protegido com TLS é fornecido:In the following appsettings.json example, an HTTP/2 endpoint secured with TLS is provided:

{
  "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 no Program.cs:Alternatively, Kestrel endpoints can be configured in 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>();
        });

Negociação de protocoloProtocol negotiation

O TLS é usado para mais do que proteger a comunicação.TLS is used for more than securing communication. O handshake ALPN (negociação do 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.The TLS Application-Layer Protocol Negotiation (ALPN) handshake is used to negotiate the connection protocol between the client and the server when an endpoint supports multiple protocols. Essa negociação determina se a conexão usa HTTP/1.1 ou HTTP/2.This negotiation determines whether the connection uses HTTP/1.1 or HTTP/2.

Se um ponto de extremidade HTTP/2 estiver configurado sem TLS, os protocolos de escuta do ponto de extremidade deverão ser definidos como HttpProtocols.Http2 .If an HTTP/2 endpoint is configured without TLS, the endpoint's ListenOptions.Protocols must be set to HttpProtocols.Http2. Um ponto de extremidade com vários protocolos (por exemplo, HttpProtocols.Http1AndHttp2 ) não pode ser usado sem TLS porque não há negociação.An endpoint with multiple protocols (for example, HttpProtocols.Http1AndHttp2) can't be used without TLS because there is no negotiation. Todas as conexões com o ponto de extremidade não seguro padrão para HTTP/1.1 e chamadas gRPC falham.All connections to the unsecured endpoint default to HTTP/1.1, and gRPC calls fail.

Para obter mais informações sobre como habilitar HTTP/2 e TLS com Kestrel, consulte configuração de ponto de extremidade Kestrel.For more information on enabling HTTP/2 and TLS with Kestrel, see Kestrel endpoint configuration.

Observação

O macOS não é compatível com gRPC do ASP.NET Core com TLS.macOS doesn't support ASP.NET Core gRPC with TLS. É necessária uma configuração adicional para executar com êxito os serviços gRPC no macOS.Additional configuration is required to successfully run gRPC services on macOS. Para obter mais informações, confira Não é possível iniciar o aplicativo ASP.NET Core gRPC no macOS.For more information, see Unable to start ASP.NET Core gRPC app on macOS.

Integração com APIs de ASP.NET CoreIntegration with ASP.NET Core APIs

os serviços gRPCs têm acesso completo aos recursos de ASP.NET Core, como injeção de dependência (di) e registro em log.gRPC services have full access to the ASP.NET Core features such as Dependency Injection (DI) and Logging. Por exemplo, a implementação do serviço pode resolver um serviço de agente do contêiner DI por meio do Construtor:For example, the service implementation can resolve a logger service from the DI container via the constructor:

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, com escopo ou transitório).By default, the gRPC service implementation can resolve other DI services with any lifetime (Singleton, Scoped, or Transient).

Resolver HttpContext em métodos gRPCResolve HttpContext in gRPC methods

A API gRPC fornece acesso a alguns dados de mensagem HTTP/2, como o método, o host, o cabeçalho e os trailers.The gRPC API provides access to some HTTP/2 message data, such as the method, host, header, and trailers. O acesso é por meio do ServerCallContext argumento passado para cada método gRPC:Access is through the ServerCallContext argument passed to each gRPC method:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContextnão fornece acesso completo ao HttpContext em todas as APIs do ASP.net.ServerCallContext does not provide full access to HttpContext in all ASP.NET APIs. O GetHttpContext método de extensão fornece acesso completo à HttpContext representação da mensagem http/2 subjacente em APIs ASP.net:The GetHttpContext extension method provides full access to the HttpContext representing the underlying HTTP/2 message in 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 adicionaisAdditional resources