Eseguire la migrazione di gRPC da C-core a gRPC per .NET

A causa dell'implementazione dello stack sottostante, non tutte le funzionalità funzionano nello stesso modo tra le app gRPC basate su C core e gRPC per .NET. Questo documento illustra le differenze principali per la migrazione tra i due stack.

Importante

gRPC C-core è in modalità di manutenzione e verrà deprecato a favore di gRPC per .NET. GRPC C-core non è consigliato per le nuove app.

Piattaforme supportate

GRPC C-core e gRPC per .NET hanno un supporto della piattaforma diverso:

• gRPC C-core: implementazione GRPC C++ con i propri stack TLS e HTTP/2. Il Grpc.Core pacchetto è un wrapper .NET intorno a gRPC C-core e contiene un client e un server gRPC. Supporta .NET Framework, .NET Core e .NET 5 o versione successiva.
• gRPC per .NET: progettato per .NET Core 3.x e .NET 5 o versione successiva. Usa stack TLS e HTTP/2 incorporati nelle versioni moderne di .NET. Il Grpc.AspNetCore pacchetto contiene un server gRPC ospitato in ASP.NET Core e richiede .NET Core 3.x o .NET 5 o versione successiva. Il Grpc.Net.Client pacchetto contiene un client gRPC. Il client in Grpc.Net.Client ha un supporto limitato per .NET Framework tramite WinHttpHandler.

Per altre informazioni, vedere gRPC nelle piattaforme supportate da .NET.

Configurare server e canale

I pacchetti NuGet, la configurazione e il codice di avvio devono essere modificati durante la migrazione da gRPC C-Core a gRPC per .NET.

gRPC per .NET include pacchetti NuGet separati per il client e il server. I pacchetti aggiunti dipendono dal fatto che un'app stia ospitando servizi gRPC o chiamandoli:

• Grpc.AspNetCore: i servizi sono ospitati da ASP.NET Core. Per informazioni sulla configurazione del server, vedere gRPC services with ASP.NET Core (Servizi gRPC con ASP.NET Core).
• Grpc.Net.Client: i client usano GrpcChannel, che usa internamente la funzionalità di rete incorporata in .NET. Per informazioni sulla configurazione client, vedere Chiamare i servizi gRPC con il client .NET.

Al termine della migrazione, il Grpc.Core pacchetto deve essere rimosso dall'app. Grpc.Core contiene file binari nativi di grandi dimensioni e la rimozione del pacchetto riduce il tempo di ripristino nuGet e le dimensioni dell'app.

Servizi e client generati dal codice

gRPC C-Core e gRPC per .NET condividono molte API e il codice generato dai .proto file è compatibile con entrambe le implementazioni gRPC. La maggior parte dei client e dei servizi può essere migrata da C-Core a gRPC per .NET senza modifiche.

Durata dell'implementazione del servizio gRPC

Nello stack ASP.NET Core, i servizi gRPC, per impostazione predefinita, vengono creati con una durata con ambito. Al contrario, gRPC C-core per impostazione predefinita si associa a un servizio con una durata singleton.

Una durata con ambito consente all'implementazione del servizio di risolvere altri servizi con durate con ambito. Ad esempio, una durata con ambito può essere risolta DbContext anche dal contenitore di inserimento delle dipendenze tramite l'inserimento del costruttore. Uso della durata con ambito:

• Viene creata una nuova istanza dell'implementazione del servizio per ogni richiesta.
• Non è possibile condividere lo stato tra le richieste tramite membri dell'istanza nel tipo di implementazione.
• Si prevede di archiviare gli stati condivisi in un servizio singleton nel contenitore di inserimento delle dipendenze. Gli stati condivisi archiviati vengono risolti nel costruttore dell'implementazione del servizio gRPC.

Per altre informazioni sulla durata del servizio, vedere Inserimento delle dipendenze in ASP.NET Core.

Aggiungere un servizio singleton

Per facilitare la transizione da un'implementazione GRPC C-core a ASP.NET Core, è possibile modificare la durata del servizio dell'implementazione del servizio dall'ambito al singleton. Ciò comporta l'aggiunta di un'istanza dell'implementazione del servizio al contenitore di inserimento delle dipendenze:

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

Tuttavia, un'implementazione del servizio con una durata singleton non è più in grado di risolvere i servizi con ambito tramite l'inserimento del costruttore.

Configurare le opzioni dei servizi gRPC

Nelle app basate su C core, le impostazioni come grpc.max_receive_message_length e grpc.max_send_message_length vengono configurate con ChannelOption durante la costruzione dell'istanza del server.

In ASP.NET Core gRPC fornisce la configurazione tramite il GrpcServiceOptions tipo . Ad esempio, è possibile configurare le dimensioni massime dei messaggi in ingresso di un servizio gRPC tramite AddGrpc. L'esempio seguente modifica il valore predefinito MaxReceiveMessageSize di 4 MB a 16 MB:

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

Per altre informazioni sulla configurazione, vedere configurazione di gRPC per .NET.

Registrazione

Le app basate su C core si basano su GrpcEnvironment per configurare il logger a scopo di debug. Lo stack ASP.NET Core fornisce questa funzionalità tramite l'API di registrazione. Ad esempio, un logger può essere aggiunto al servizio gRPC tramite l'inserimento del costruttore:

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

Per altre informazioni sulla registrazione e la diagnostica gRPC, vedere Registrazione e diagnostica in gRPC in .NET.

HTTPS

Le app basate su C core configurano HTTPS tramite la proprietà Server.Ports. Un concetto simile viene usato per configurare i server in ASP.NET Core. Ad esempio, Kestrel usa la configurazione degli endpoint per questa funzionalità.

Intercettori gRPC

ASP.NET middleware Core offre funzionalità simili rispetto agli intercettori nelle app gRPC basate su C core. Entrambi sono supportati dalle app ASP.NET Core gRPC, quindi non è necessario riscrivere gli intercettori.

Per altre informazioni sul confronto tra queste funzionalità, vedere gRPC Interceptors e middleware.

Ospitare gRPC nei progetti non-ASP.NET Core

Un server basato su C core può essere aggiunto a qualsiasi tipo di progetto. gRPC per il server .NET richiede ASP.NET Core. ASP.NET Core è in genere disponibile perché il file di progetto specifica Microsoft.NET.SDK.Web come SDK.

Un server gRPC può essere ospitato in non-ASP.NET progetti Core aggiungendo <FrameworkReference Include="Microsoft.AspNetCore.App" /> a un progetto. Il riferimento al framework rende disponibili ASP.NET API Core e possono essere usate per avviare un server ASP.NET Core.

Per altre informazioni, vedere Ospitare gRPC nei progetti non-ASP.NET Core.

Risorse aggiuntive

• Panoramica di gRPC in .NET
• Servizi gRPC con C#
• Servizi gRPC con ASP.NET Core
• Creare un client e un server gRPC di .NET Core in ASP.NET Core