Migrowanie gRPC z C-core do gRPC dla platformy .NET

Ze względu na implementację bazowego stosu nie wszystkie funkcje działają w ten sam sposób między aplikacjami gRPC opartymi na języku C i gRPC dla platformy .NET. W tym dokumencie przedstawiono kluczowe różnice w migracji między dwoma stosami.

Ważne

gRPC C-core jest w trybie konserwacji i zostanie wycofany na rzecz gRPC na platformie .NET. gRPC C-core nie jest zalecany do nowych aplikacji.

Obsługa platform

GRPC C-core i gRPC dla platformy .NET mają inną obsługę platformy:

• gRPC C-core: implementacja GRPC języka C++ z własnymi stosami TLS i HTTP/2. Pakiet Grpc.Core jest opakowaniem .NET wokół rdzenia C-core gRPC i zawiera klienta oraz serwer gRPC. Obsługuje ona programy .NET Framework, .NET Core i .NET 5 lub nowsze.
• gRPC dla platformy .NET: przeznaczony dla platform .NET Core 3.x i .NET 5 lub nowszych. Używa on stosów TLS i HTTP/2 wbudowanych w nowoczesne wersje platformy .NET. Pakiet Grpc.AspNetCore zawiera serwer gRPC, który jest hostowany w ASP.NET Core i wymaga platformy .NET Core 3.x lub .NET 5 lub nowszej. Pakiet Grpc.Net.Client zawiera klienta gRPC. Klient w Grpc.Net.Client ma ograniczoną obsługę .NET Framework przy użyciu WinHttpHandler.

Aby uzyskać więcej informacji, zobacz gRPC na obsługiwanych platformach .NET.

Konfigurowanie serwera i kanału

Pakiety NuGet, konfiguracja i kod uruchamiania muszą być modyfikowane podczas migracji z GRPC C-Core do gRPC dla platformy .NET.

Usługa gRPC dla platformy .NET ma oddzielne pakiety NuGet dla swojego klienta i serwera. Dodane pakiety zależą od tego, czy aplikacja hostuje usługi gRPC, czy wywołuje je:

• Grpc.AspNetCore: Usługi są hostowane przez ASP.NET Core. Aby uzyskać informacje o konfiguracji serwera, zobacz usługi gRPC z ASP.NET Core.
• Grpc.Net.Client: Klienci używają programu GrpcChannel, który wewnętrznie używa funkcji sieci wbudowanych w platformę .NET. Aby uzyskać informacje o konfiguracji klienta, zobacz Wywoływanie usług gRPC za pomocą klienta platformy .NET.

Po zakończeniu Grpc.Core migracji pakiet powinien zostać usunięty z aplikacji. Grpc.Core zawiera duże pliki binarne natywne, a usunięcie pakietu skraca czas przywracania NuGet i rozmiar aplikacji.

Wygenerowane przez kod usługi i klienci

gRPC C-Core i gRPC dla platformy .NET mają wiele wspólnych interfejsów API, a kod generowany z plików .proto jest zgodny z oboma implementacjami gRPC. Większość klientów i usług można migrować z C-Core do gRPC dla platformy .NET bez zmian.

Okres istnienia implementacji usługi gRPC

W stosie ASP.NET Core usługi gRPC domyślnie są tworzone z okresem istnienia o określonym zakresie. Z kolei gRPC C-core domyślnie wiąże się z usługą z pojedynczym okresem istnienia.

Okres istnienia o określonym zakresie umożliwia implementacji usługi rozpoznawanie innych usług z okresami istnienia o określonym zakresie. Na przykład cykl życia o określonym zakresie może również zostać rozwiązany DbContext z kontenera DI za pomocą iniekcji konstruktora. Korzystanie z czasem życia o ograniczonym zasięgu:

• Nowa instancja implementacji usługi jest tworzona dla każdego żądania.
• Nie można współużytkować stanu między żądaniami za pośrednictwem pól instancji w typie implementacji.
• Oczekuje się, że stany udostępnione będą przechowywane w usłudze singleton w kontenerze DI. Stany współdzielone, które są przechowywane, są rozwiązywane w konstruktorze implementacji usługi gRPC.

Aby uzyskać więcej informacji na temat okresów istnienia usługi, zobacz Wstrzykiwanie zależności w programie ASP.NET Core.

Dodaj usługę singleton

Aby ułatwić przejście z implementacji gRPC opartej na C-core do ASP.NET Core, można zmienić czas życia implementacji usługi z zakresu na singleton. Polega to na dodaniu instancji implementacji usługi do kontenera DI.

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

Jednak implementacja usługi z pojedynczym okresem istnienia nie jest już w stanie rozpoznać usług o określonym zakresie za pomocą iniekcji konstruktora.

Konfigurowanie opcji usług gRPC

W aplikacjach opartych na rdzeniu C ustawienia, takie jak grpc.max_receive_message_length i grpc.max_send_message_length, są konfigurowane z ChannelOption podczas konstruowania wystąpienia serwera.

W ASP.NET Core gRPC zapewnia konfigurację za pośrednictwem typu GrpcServiceOptions. Na przykład usługa gRPC może skonfigurować maksymalny rozmiar komunikatu przychodzącego za pomocą polecenia AddGrpc. Poniższy przykład zmienia domyślną wartość MaxReceiveMessageSize 4 MB na 16 MB:

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

Aby uzyskać więcej informacji na temat konfiguracji, zobacz gRPC dla konfiguracji platformy .NET.

Logowanie

Aplikacje oparte na C-core polegają na GrpcEnvironment, aby konfigurować rejestrator na potrzeby debugowania. Stos ASP.NET Core zapewnia tę funkcję za pośrednictwem interfejsu API rejestrowania. Na przykład rejestrator można dodać do usługi gRPC.

Wstrzykiwanie konstruktora:

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

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

Iniekcja konstruktora podstawowego (.NET 8 lub nowszy):

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

Aby uzyskać więcej informacji na temat rejestrowania i diagnostyki gRPC, zobacz Rejestrowanie i diagnostyka w usłudze gRPC na platformie .NET.

HTTPS

Aplikacje oparte na języku C konfigurują protokół HTTPS za pomocą właściwości Server.Ports. Podobna koncepcja służy do konfigurowania serwerów w programie ASP.NET Core. Na przykład Kestrel używa konfiguracji punktu końcowego dla tej funkcji.

Przechwytniki gRPC

oprogramowanie pośredniczące ASP.NET Core oferuje podobne funkcje w porównaniu do interceptorów w aplikacjach gRPC opartych na C-core. Oba są obsługiwane przez aplikacje gRPC ASP.NET Core, więc nie ma potrzeby ponownego tworzenia interceptorów.

Aby uzyskać więcej informacji na temat porównywania tych funkcji ze sobą, zobacz gRPC Interceptors and Middleware (Przechwytywanie gRPC i oprogramowanie pośredniczące).

Hostowanie usługi gRPC w projektach non-ASP.NET Core

Serwer oparty na języku C można dodać do dowolnego typu projektu. GRPC dla serwera .NET wymaga ASP.NET Core. ASP.NET Core jest zwykle dostępna, ponieważ plik projektu określa Microsoft.NET.SDK.Web jako zestaw SDK.

Serwer gRPC może być hostowany dla projektów innych niż ASP.NET Core przez dodanie <FrameworkReference Include="Microsoft.AspNetCore.App" /> do projektu. Odwołanie do frameworka udostępnia API ASP.NET Core i mogą być używane do uruchamiania serwera ASP.NET Core.

Aby uzyskać więcej informacji, zobacz Host gRPC w projektach niezwiązanych z ASP.NET Core.

Dodatkowe zasoby

• Omówienie usługi gRPC na platformie .NET
• usługi gRPC z językiem C#
• Usługi gRPC z platformą ASP.NET Core
• Tworzenie klienta i serwera gRPC platformy .NET Core na platformie ASP.NET Core