Migrar gRPC do C-core para o gRPC para .NET

Devido à implementação da pilha subjacente, nem todos os recursos funcionam da mesma forma entre aplicativos gRPC baseados em C-core e o gRPC para .NET. Este documento realça as principais diferenças para migrar entre as duas pilhas.

Importante

O gRPC C-core está no modo de manutenção e será preterido em favor do gRPC para .NET. O gRPC C-core não é recomendado para novos aplicativos.

Suporte a plataforma

O gRPC C-core e o gRPC para .NET têm suporte de plataforma diferente:

• gRPC C-core: uma implementação de gRPC C++ com suas próprias pilhas TLS e HTTP/2. O pacote Grpc.Core é um wrapper do .NET em torno do gRPC C-core e contém um cliente e um servidor gRPC. Ele dá suporte a .NET Framework, .NET Core e .NET 5 ou posteriores.
• gRPC para .NET: projetado para .NET Core 3.x e .NET 5 ou posteriores. Ele usa pilhas TLS e HTTP/2 incorporadas a versões modernas do .NET. O pacote Grpc.AspNetCore contém um servidor gRPC hospedado no ASP.NET Core e requer o .NET Core 3.x ou o .NET 5 e versões posteriores. O pacote Grpc.Net.Client contém um cliente gRPC. O cliente no Grpc.Net.Client tem suporte limitado para o .NET Framework usando WinHttpHandler.

Para obter mais informações, confira gRPC em plataformas com suporte do .NET.

Configurar servidor e canal

Pacotes NuGet, configuração e código de inicialização devem ser modificados ao migrar do gRPC C-Core para o gRPC para .NET.

O gRPC para .NET tem pacotes NuGet separados para seu cliente e servidor. Os pacotes adicionados dependem se um aplicativo está hospedando serviços gRPC ou chamando-os:

• Grpc.AspNetCore: os serviços são hospedados pelo ASP.NET Core. Para obter informações de configuração do servidor, confira Serviços gRPC com o ASP.NET Core.
• Grpc.Net.Client: os clientes usam GrpcChannel, que usa internamente a funcionalidade de rede interna no .NET. Para obter informações de configuração do cliente, confira Chamar serviços gRPC com o cliente .NET.

Quando a migração for concluída, o pacote Grpc.Core deverá ser removido do aplicativo. Grpc.Core contém binários nativos grandes e a remoção do pacote reduz o tempo de restauração do NuGet e o tamanho do aplicativo.

Serviços e clientes gerados por código

gRPC C-Core e gRPC para .NET compartilham muitas APIs e o código gerado a partir de arquivos .proto é compatível com ambas as implementações de gRPC. A maioria dos clientes e serviços pode ser migrada do C-Core para o gRPC para .NET sem alterações.

Tempo de vida de implementação do serviço gRPC

Na pilha do ASP.NET Core, os serviços gRPC, por padrão, são criados com um tempo de vida com escopo. Por outro lado, o gRPC C-core por padrão se associa a um serviço com um tempo de vida singleton.

Um tempo de vida com escopo permite que a implementação do serviço resolve outros serviços com tempos de vida com escopo. Por exemplo, um tempo de vida com escopo também pode resolver DbContext do contêiner de DI por meio da injeção de construtor. Usando o tempo de vida com escopo:

• Uma nova instância da implementação do serviço é construída para cada solicitação.
• Não é possível compartilhar o estado entre solicitações por meio de membros de instância no tipo de implementação.
• A expectativa é armazenar estados compartilhados em um serviço singleton no contêiner de DI. Os estados compartilhados armazenados são resolvidos no construtor da implementação do serviço do gRPC.

Para obter mais informações sobre os tempos de vida do serviço, confira Injeção de dependência no ASP.NET Core.

Adicionar um serviço singleton

Para facilitar a transição de uma implementação de gRPC C-core para o ASP.NET Core, é possível alterar o tempo de vida do serviço da implementação do serviço de escopo para singleton. Isso envolve a adição de uma instância da implementação do serviço ao contêiner de DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
    services.AddSingleton(new GreeterService());
}

No entanto, uma implementação de serviço com um tempo de vida singleton não é mais capaz de resolver serviços com escopo por meio da injeção de construtor.

Configurar opções de serviços gRPC

Em aplicativos baseados em C-core, configurações como grpc.max_receive_message_length e grpc.max_send_message_length são configuradas com ChannelOption ao construir a instância do servidor.

No ASP.NET Core, o gRPC fornece configuração por meio do tipo GrpcServiceOptions. Por exemplo, o tamanho máximo da mensagem de entrada de um serviço do gRPC pode ser configurado por meio de AddGrpc. O exemplo a seguir altera o padrão MaxReceiveMessageSize de 4 MB para 16 MB:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc(options =>
    {
        options.MaxReceiveMessageSize = 16 * 1024 * 1024; // 16 MB
    });
}

Para obter mais informações sobre a configuração, confira gRPC para configuração do .NET.

Log

Os aplicativos baseados em C-core dependem do GrpcEnvironment para configurar o agente para fins de depuração. A pilha do ASP.NET Core fornece essa funcionalidade por meio da API de registro em log. Por exemplo, um agente pode ser adicionado ao serviço gRPC por meio de injeção de construtor:

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

Para obter mais informações sobre diagnóstico e registro em log do gRPC, confira Registro em log e diagnóstico no gRPC no .NET.

HTTPS

Os aplicativos baseados em C-core configuram o HTTPS por meio da propriedade Server.Ports. Um conceito semelhante é usado para configurar servidores no ASP.NET Core. Por exemplo, Kestrel usa a configuração de ponto de extremidade para essa funcionalidade.

Interceptores de gRPC

O middleware do ASP.NET Core oferece funcionalidades semelhantes em comparação com interceptadores em aplicativos gRPC baseados em C-core. Ambos são compatíveis com aplicativos gRPC do ASP.NET Core, portanto, não há necessidade de reescrever interceptadores.

Para obter mais informações sobre como esses recursos se comparam entre si, confira Interceptores gRPC versus Middleware.

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

Um servidor baseado em C-core pode ser adicionado a qualquer tipo de projeto. O gRPC para servidor .NET requer o ASP.NET Core. O ASP.NET Core geralmente está disponível porque o arquivo de projeto especifica Microsoft.NET.SDK.Web como o SDK.

Um servidor gRPC pode ser hospedado em projetos que não sejam do ASP.NET Core adicionando <FrameworkReference Include="Microsoft.AspNetCore.App" /> a um projeto. A referência da estrutura disponibiliza APIs do ASP.NET Core e elas podem ser usadas para iniciar um servidor ASP.NET Core.

Para mais informações, confira Hospedar gRPC em projetos que não são do ASP.NET Core.

Recursos adicionais

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