Migrar gRPC de C-core para gRPC para .NET

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

Suporte à plataforma

gRPC C-core e gRPC para .NET têm suporte a plataformas diferentes:

• gRPC C-core: Uma implementação gRPC C++ com as suas próprias stacks TLS e HTTP/2. O pacote Grpc.Core é um wrapper .NET em torno do gRPC C-core e contém um cliente e um servidor gRPC. Ele suporta .NET Framework, .NET Core e .NET 5 ou posterior.
• gRPC para .NET: Projetado para .NET Core 3.x e .NET 5 ou posterior. Ele usa pilhas TLS e HTTP/2 incorporadas em 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 .NET 5 ou posterior. O pacote Grpc.Net.Client contém um cliente gRPC. O cliente no Grpc.Net.Client tem suporte limitado para .NET Framework usando WinHttpHandler.

Para obter mais informações, consulte gRPC nas plataformas suportadas pelo .NET.

Configurar servidor e canal

Os pacotes, a configuração e o código de inicialização do NuGet 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 de se um aplicativo hospeda serviços gRPC ou os chama.

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

Quando a migração estiver 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 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 da implementação do serviço gRPC

Na pilha ASP.NET Core, os serviços gRPC, por padrão, são criados com um de tempo de vida com escopo. Em contraste, gRPC C-core por padrão se liga a um serviço com um de vida útil singleton.

Um tempo de vida com escopo permite que a implementação do serviço resolva outros serviços com tempos de vida definidos. Por exemplo, um tempo de vida com escopo também pode resolver DbContext do contêiner DI por meio da injeção do construtor. Usando o tempo de vida do 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 da instância no tipo de implementação.
• A expectativa é armazenar estados partilhados num serviço singleton no contentor DI. Os estados compartilhados armazenados são resolvidos no construtor da implementação do serviço gRPC.

Para obter mais informações sobre a vida útil do serviço, consulte Injeção de dependência no ASP.NET Core.

Adicionar um serviço singleton

Para facilitar a transição de uma implementação C-core gRPC para ASP.NET Core, é possível alterar o tempo de vida 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 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 do construtor.

Configurar opções de serviços gRPC

Em aplicações baseadas em C-core, definições como grpc.max_receive_message_length e grpc.max_send_message_length são ajustadas com ChannelOption durante a construção da instância do Servidor.

No ASP.NET Core, o gRPC fornece configuração através do tipo GrpcServiceOptions. Por exemplo, o tamanho máximo de mensagem recebida de um serviço gRPC pode ser configurado através AddGrpc. O exemplo a seguir altera o MaxReceiveMessageSize padrão 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 configuração, consulte gRPC for .NET configuration.

Registo

Os aplicativos baseados em C-core dependem do GrpcEnvironment ao para configurar o logger para fins de depuração. A pilha ASP.NET Core fornece essa funcionalidade através da API de Logging . Por exemplo, um registrador pode ser adicionado ao serviço gRPC.

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
{
    ...
}

Para obter mais informações sobre o registo e o diagnóstico do gRPC, consulte Logging and diagnostics in gRPC on .NET.

HTTPS

Intercetores gRPC

ASP.NET de middleware Core oferece funcionalidades semelhantes em comparação com intercetadores em aplicativos gRPC baseados em C-core. Ambos são suportados por aplicações gRPC ASP.NET Core, portanto, não há necessidade de reescrever interceptores.

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

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

Um servidor baseado em C-core pode ser adicionado a qualquer tipo de projeto. gRPC para servidor .NET requer ASP.NET Core. 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 ASP.NET Core adicionando <FrameworkReference Include="Microsoft.AspNetCore.App" /> a um projeto. A referência de estrutura disponibiliza APIs ASP.NET Core e elas podem ser usadas para iniciar um servidor ASP.NET Core.

Para obter mais informações, consulte Hospedar gRPC em projetos fora do ASP.NET Core.

Recursos adicionais

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