Migrace gRPC z C-Core na gRPC pro .NET

Vzhledem k implementaci základního zásobníku nefungují všechny funkce stejným způsobem mezi aplikacemi gRPC založenými na C a gRPC pro .NET. Tento dokument zdůrazňuje hlavní rozdíly při přechodu mezi těmito dvěma technologickými sadami.

Důležité

GRPC C-core je v režimu údržby a bude vyřazen ve prospěch gRPC pro .NET. Pro nové aplikace se nedoporučuje gRPC C-core.

Podpora platformy

GRPC C-core a gRPC pro .NET mají podporu různých platforem:

• gRPC C-core: Implementace gRPC v C++ s vlastními zásobníky TLS a HTTP/2. Balíček Grpc.Core je obálka .NET kolem gRPC C-Core a obsahuje klienta a server gRPC. Podporuje rozhraní .NET Framework, .NET Core a .NET 5 nebo novější.
• gRPC pro .NET: Určeno pro .NET Core 3.x a .NET 5 nebo novější. Využívá zásobníky TLS a HTTP/2, které jsou integrovány do současných verzí platformy .NET. Balíček Grpc.AspNetCore obsahuje server gRPC hostovaný v ASP.NET Core a vyžaduje .NET Core 3.x nebo .NET 5 nebo novější. Balíček Grpc.Net.Client obsahuje klienta gRPC. Klient v Grpc.Net.Client má omezenou podporu pro .NET Framework pomocí WinHttpHandler.

Další informace najdete v tématu gRPC na podporovaných platformách .NET.

Konfigurace serveru a kanálu

Balíčky NuGet, konfigurace a spouštěcí kód musí být změněny při migraci z gRPC C-Core na gRPC pro .NET.

gRPC pro .NET obsahuje samostatné balíčky NuGet pro svého klienta a serveru. Přidané balíčky závisí na tom, jestli aplikace hostuje služby gRPC nebo je volá:

• Grpc.AspNetCore: Služby hostuje ASP.NET Core. Informace o konfiguraci serveru najdete v tématu služby gRPC s ASP.NET Core.
• Grpc.Net.Client: Klienti používají GrpcChannel, který interně používá síťové funkce integrované do .NET. Informace o konfiguraci klienta naleznete v Volání služeb gRPC s klientem .NET.

Po dokončení Grpc.Core migrace by se balíček měl z aplikace odebrat. Grpc.Core obsahuje velké nativní binární soubory a odebrání balíčku snižuje čas obnovení NuGet a velikost aplikace.

Generovaný kód služeb a klientů

gRPC C-Core a gRPC pro .NET sdílí mnoho rozhraní API a kód vygenerovaný ze .proto souborů je kompatibilní s oběma implementacemi gRPC. Většina klientů a služeb je možné migrovat z C-Core na gRPC pro .NET beze změn.

Životnost implementace služby gRPC

Ve výchozím nastavení se v zásobníku ASP.NET Core vytvářejí služby gRPC s vymezenou životností. Naproti tomu gRPC C-core ve výchozím nastavení váže na službu s jednotnou životností.

Vymezená životnost umožňuje implementaci služby vyřešit jiné služby s vymezenými životnostmi. Například životnost s omezeným dosahem se dá také vyřešit z kontejneru DI prostřednictvím konstruktorové injekce. Použití doby platnosti s vymezeným oborem:

• Pro každý požadavek se vytvoří nová instance implementace služby.
• Stav mezi požadavky není možné sdílet prostřednictvím členů instance v typu implementace.
• Očekávání spočívá v ukládání sdílených stavů ve službě singleton v kontejneru DI. Uložené sdílené stavy jsou vyřešeny v konstruktoru implementace služby gRPC.

Další informace o životnosti služeb najdete v tématu Injektáž závislostí v ASP.NET Core.

Přidat singleton službu

Pro usnadnění přechodu z implementace gRPC C-core na ASP.NET Core je možné změnit dobu platnosti implementace služby z "scoped" na "singleton". To zahrnuje přidání instance implementace služby do kontejneru DI:

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

Implementace služby s jednou životností už ale nedokáže vyřešit omezené služby prostřednictvím injektáže konstruktoru.

Konfigurace možností služeb gRPC

V aplikacích založených na C-core se nastavení jako grpc.max_receive_message_length a grpc.max_send_message_length konfigurují ChannelOption při vytváření instance serveru.

V ASP.NET Core poskytuje gRPC konfiguraci prostřednictvím GrpcServiceOptions typu. Například službu gRPC je možné nakonfigurovat maximální velikost příchozí zprávy prostřednictvím AddGrpc. Následující příklad změní výchozí MaxReceiveMessageSize hodnotu 4 MB na 16 MB:

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

Další informace o konfiguraci najdete v tématu gRPC pro konfiguraci .NET.

Protokolování

Aplikace založené na C-core spoléhají na GrpcEnvironment k konfiguraci protokolovacího nástroje pro účely ladění. Zásobník ASP.NET Core poskytuje tuto funkci prostřednictvím Logging API. Do služby gRPC lze například přidat logger.

Injektáž konstruktoru:

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

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

Injektáž primárního konstruktoru (.NET 8 nebo novější):

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

Další informace o protokolování a diagnostice gRPC naleznete v tématu Protokolování a diagnostika v gRPC v .NET.

HTTPS

Aplikace založené na jádrech C konfigurují HTTPS prostřednictvím vlastnosti Server.Ports. Podobný koncept se používá ke konfiguraci serverů v ASP.NET Core. Například Kestrel k této funkci používá konfiguraci koncového bodu.

Průsečíky gRPC

ASP.NET Core middleware nabízí podobné funkce jako interceptory v aplikacích založených na C-core pro gRPC. Obě aplikace podporují ASP.NET core gRPC, takže není nutné přepisovat průsečíky.

Další informace o porovnání těchto funkcí najdete v tématu gRPC Interceptors versus Middleware.

Hostování gRPC v projektech non-ASP.NET Core

Server založený na jádru C lze přidat do libovolného typu projektu. GRPC pro server .NET vyžaduje ASP.NET Core. ASP.NET Core je obvykle k dispozici, protože soubor projektu určuje Microsoft.NET.SDK.Web jako sadu SDK.

Server gRPC je možné hostovat do non-ASP.NET základních projektů přidáním <FrameworkReference Include="Microsoft.AspNetCore.App" /> do projektu. Referenční dokumentace k rozhraní ASP.NET Core API je k dispozici a lze ji použít ke spuštění serveru ASP.NET Core.

Další informace najdete v tématu Host gRPC v projektech non-ASP.NET Core.

Další materiály

• Přehled gRPC v .NET
• Služby gRPC s C#
• Služby gRPC s ASP.NET Core
• Vytvoření serveru a klienta .NET Core gRPC v ASP.NET Core