Serviços do gRPC com o ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Aviso

Esta versão do ASP.NET Core não tem mais suporte. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

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

Pré-requisitos

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

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

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

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:

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:

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

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

Pré-requisitos

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

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

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

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:

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:

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

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

Pré-requisitos

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

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

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

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:

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:

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

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

Pré-requisitos

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

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

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

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

O gRPC requer o pacote Grpc.AspNetCore.

Configurar o gRPC

No Startup.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.
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 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:

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:

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>();
        });

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:

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

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

Pré-requisitos

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

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

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

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

O gRPC requer o pacote Grpc.AspNetCore.

Configurar o gRPC

No Startup.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.
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 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:

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:

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>();
        });

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.

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:

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

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

Pré-requisitos

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

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

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

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

O gRPC requer o pacote Grpc.AspNetCore.

Configurar o gRPC

No Startup.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.
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 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:

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:

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>();
        });

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.

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:

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