Migrera gRPC från C-core till gRPC för .NET

På grund av implementeringen av den underliggande stacken fungerar inte alla funktioner på samma sätt mellan C-core-baserade gRPC--appar och gRPC för .NET. Det här dokumentet visar de viktigaste skillnaderna för migrering mellan de två staplarna.

Viktig

gRPC C-core är i underhållsläge och kommer att bli inaktuell till förmån för gRPC för .NET. gRPC C-core rekommenderas inte för nya appar.

Plattformsstöd

gRPC C-core och gRPC för .NET har olika plattformsstöd:

• gRPC C-core: En C++ gRPC-implementering med egna TLS- och HTTP/2-staplar. Grpc.Core-paketet är en .NET-omslutning runt gRPC C-core och innehåller en gRPC-klient och -server. Den stöder .NET Framework, .NET Core och .NET 5 eller senare.
• gRPC för .NET: Utformad för .NET Core 3.x och .NET 5 eller senare. Den använder TLS- och HTTP/2-staplar inbyggda i moderna .NET-versioner. Grpc.AspNetCore-paketet innehåller en gRPC-server som finns i ASP.NET Core och som kräver .NET Core 3.x eller .NET 5 eller senare. Grpc.Net.Client-paketet innehåller en gRPC-klient. Klienten i Grpc.Net.Client har begränsat stöd för .NET Framework med hjälp av WinHttpHandler.

Mer information finns i gRPC på .NET-plattformar som stöds.

Konfigurera server och kanal

NuGet-paket, konfiguration och startkod måste ändras när du migrerar från gRPC C-Core till gRPC för .NET.

gRPC för .NET har separata NuGet-paket för klienten och servern. Vilka paket som läggs till beror på om en app är värd för gRPC-tjänster eller anropar dem:

• Grpc.AspNetCore: Tjänsterna hanteras av ASP.NET Core. Information om serverkonfiguration finns i gRPC-tjänster med ASP.NET Core.
• Grpc.Net.Client: Klienter använder GrpcChannel, som internt använder nätverksfunktioner som är inbyggda i .NET. Information om klientkonfiguration finns i Anropa gRPC-tjänster med .NET-klienten.

När migreringen är klar bör Grpc.Core-paketet tas bort från appen. Grpc.Core innehåller stora interna binärfiler och om du tar bort paketet minskar nuGet-återställningstiden och appstorleken.

Kodgenererade tjänster och klienter

gRPC C-Core och gRPC för .NET delar många API:er, och kod som genereras från .proto filer är kompatibel med båda gRPC-implementeringarna. De flesta klienter och tjänster kan migreras från C-Core till gRPC för .NET utan ändringar.

Livslängd för gRPC-tjänstimplementering

I ASP.NET Core-stacken skapas gRPC-tjänster som standard med en avgränsad livstid. GRPC C-core binder däremot som standard till en tjänst med en singleton-livslängd.

En avgränsad livstid tillåter tjänstimplementeringen att lösa andra tjänster med avgränsade livstider. En begränsad livslängd kan till exempel även lösa DbContext från DI-containern via konstruktorinmatning. Använda omfattad livslängd

• En ny instans av tjänstimplementeringen skapas för varje begäran.
• Det går inte att dela tillstånd mellan begäranden genom instansmedlemmar i implementeringstypen.
• Förväntningarna är att lagra delade tillstånd i en singleton-tjänst i DI-containern. De lagrade delade tillstånden löses i konstruktorn för gRPC-tjänstimplementeringen.

Mer information om tjänstlivslängder finns i Beroendeinmatning i ASP.NET Core.

Lägg till en singleton-tjänst

För att underlätta övergången från en gRPC C-core-implementering till ASP.NET Core är det möjligt att ändra tjänstlivslängden för tjänstimplementeringen från begränsad till singleton. Detta innebär att lägga till en instans av tjänstimplementeringen i DI-containern:

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

En tjänstimplementering med en singleton-livslängd kan dock inte längre lösa begränsade tjänster via konstruktorinmatning.

Konfigurera alternativ för gRPC-tjänster

I C-core-baserade appar konfigureras inställningar som grpc.max_receive_message_length och grpc.max_send_message_length med ChannelOption när konstruerar serverinstansen.

I ASP.NET Core tillhandahåller gRPC konfiguration via GrpcServiceOptions typ. Till exempel kan en gRPC-tjänsts maximala inkommande meddelandestorlek konfigureras via AddGrpc. I följande exempel ändras standard MaxReceiveMessageSize på 4 MB till 16 MB:

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

Mer information om konfiguration finns i gRPC för .NET-konfiguration.

Skogsavverkning

C-core-baserade appar förlitar sig på GrpcEnvironment och för att konfigurera logger för felsökningsändamål. ASP.NET Core-stacken tillhandahåller den här funktionen via loggnings-API:et. Till exempel kan en logger läggas till i gRPC-tjänsten.

Konstruktorinmatning:

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;

    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }
}

Primär konstruktorinmatning (.NET 8 eller senare):

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

Mer information om gRPC-loggning och diagnostik finns i Loggning och diagnostik i gRPC på .NET.

HTTPS

C-core-baserade appar konfigurerar HTTPS via egenskapen Server.Ports. Ett liknande begrepp används för att konfigurera servrar i ASP.NET Core. Till exempel använder Kestrelslutpunktskonfiguration för den här funktionen.

gRPC-avlyssnare

ASP.NET Core mellanprogram erbjuder liknande funktioner jämfört med interceptorer i C-core-baserade gRPC-appar. Båda stöds av ASP.NET Core gRPC-appar, så det finns inget behov av att skriva om interceptorer.

Mer information om hur dessa funktioner jämförs med varandra finns i gRPC Interceptors kontra Middleware.

Värd för gRPC i non-ASP.NET Core-projekt

En C-core-baserad server kan läggas till i valfri projekttyp. gRPC för .NET-servern kräver ASP.NET Core. ASP.NET Core är vanligtvis tillgängligt eftersom projektfilen anger Microsoft.NET.SDK.Web som SDK.

En gRPC-server kan finnas i non-ASP.NET Core-projekt genom att lägga till <FrameworkReference Include="Microsoft.AspNetCore.App" /> i ett projekt. Ramverksreferensen gör ASP.NET Core API:er tillgängliga och de kan användas för att starta en ASP.NET Core-server.

Mer information finns i Värd gRPC i icke-ASP.NET Core-projekt.

Ytterligare resurser

• Översikt över gRPC på .NET
• gRPC-tjänster med C#
• gRPC-tjänster med ASP.NET Core
• Skapa en .NET Core gRPC-klient och -server i ASP.NET Core