Migrieren von gRPC von C-core zu gRPC für .NET

Aufgrund der Implementierung des zugrundeliegenden Stapels funktionieren nicht alle Features in C-core-basierten gRPC-Apps und gRPC für .NET.gleich. In diesem Artikel wird auf die Hauptunterschiede zwischen den beiden Stapeln in Bezug auf die Migration eingegangen.

Wichtig

gRPC C-Core befindet sich im Wartungsmodus und wird als veraltet eingestuft und durch gRPC für .NET ersetzt. gRPC C-Core wird für neue Apps nicht empfohlen.

Plattformunterstützung

gRPC C-core und gRPC für .NET bieten eine unterschiedliche Plattformunterstützung:

• gRPC C-core: Eine C++-gRPC-Implementierung mit eigenen TLS- und HTTP/2-Stapeln. Das Grpc.Core-Paket ist ein .NET-Wrapper um gRPC C-core und umfasst einen gRPC-Client und -Server. Es unterstützt .NET Framework, .NET Core und .NET 5 oder höher.
• gRPC für .NET: Entwickelt für .NET Core 3.x und .NET 5 oder höher. Es werden TLS- und HTTP/2-Stapel verwendet, die in moderne .NET-Releases integriert sind. Das Grpc.AspNetCore-Paket enthält einen gRPC-Server, der in ASP.NET Core gehostet wird und .NET Core 3.x oder .NET 5 oder höher erfordert. Das Grpc.Net.Client-Paket umfasst einen gRPC-Client. Der Client in Grpc.Net.Client bietet eingeschränkte Unterstützung für .NET Framework unter Verwendung von WinHttpHandler.

Weitere Informationen finden Sie unter gRPC auf .NET-unterstützten Plattformen.

Konfigurieren von Server und Kanal

NuGet-Pakete, Konfiguration und Startcode müssen bei der Migration von gRPC für C-Core zu gRPC für .NET angepasst werden.

gRPC für .NET verfügt über separate NuGet-Pakete für seinen Client und Server. Die hinzugefügten Pakete hängen davon ab, ob eine App gRPC-Dienste hostet oder sie aufruft:

• Grpc.AspNetCore: Dienste werden von ASP.NET Core gehostet. Informationen zur Serverkonfiguration finden Sie unter gRPC-Dienste mit ASP.NET Core.
• Grpc.Net.Client: Clients verwenden GrpcChannel, wofür intern die in .NET integrierte Netzwerkfunktionalität genutzt wird. Informationen zur Clientkonfiguration finden Sie unter Aufrufen von gRPC-Diensten mit dem .NET-Client.

Nach Abschluss der Migration muss das Paket Grpc.Core aus der App entfernt werden. Grpc.Core enthält große native Binärdateien, sodass das Entfernen des Pakets die NuGet-Wiederherstellungszeit und App-Größe reduziert.

Per Code generierte Dienste und Clients

gRPC für C-Core und gRPC für .NET nutzen viele APIs gemeinsam, und der aus .proto-Dateien generierte Code ist mit beiden gRPC-Implementierungen kompatibel. Die meisten Clients und Dienste können ohne Änderungen von C-Core zu gRPC für .NET migriert werden.

Lebensdauer der gRPC-Dienstimplementierung

Im ASP.NET Core-Stapel werden gRPC-Dienste standardmäßig mit bereichsbezogener Lebensdauer erstellt. Im Gegensatz hierzu ist gRPC-C-core standardmäßig an einen Dienst mit Singletonlebensdauer gebunden.

Die bereichsbezogene Lebensdauer ermöglicht es der Dienstimplementierung, andere Dienste mit bereichsbezogener Lebensdauer aufzulösen. Bei einer bereichsbezogenen Lebensdauer kann beispielsweise auch DbContext durch Konstruktorinjektion aus dem Abhängigkeitsinjektionscontainer aufgelöst werden. Wenn bereichsbezogene Lebensdauer verwendet wird:

• wird für jede Anforderung eine neue Instanz der Dienstimplementierung konstruiert.
• ist es nicht möglich, Zustände zwischen Anforderungen über Instanzmember für den Implementierungstyp freizugeben.
• wird erwartet, dass freigegebene Zustände in einem Singletondienst im Abhängigkeitsinjektionscontainer gespeichert werden. Die gespeicherten freigegebenen Zustände werden im Konstruktor der gRPC-Dienstimplementierung aufgelöst.

Weitere Informationen zur Lebensdauer von Diensten finden Sie unter Abhängigkeitsinjektion in ASP.NET Core.

Hinzufügen eines Singletondiensts

Die Übertragung einer gRPC-C-core-Implementierung in ASP.NET Core kann vereinfacht werden, indem die Lebensdauer der Dienstimplementierung von bereichsbezogen in Singleton geändert wird. Hierbei wird eine Instanz der Dienstimplementierung zum Abhängigkeitsinjektionscontainer hinzugefügt:

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

Eine Dienstimplementierung mit Singletonlebensdauer kann allerdings bereichsbezogene Dienste nicht mehr durch Konstruktorinjektion auflösen.

Konfigurieren von Optionen für gRPC-Dienste

In C-core-basierten Apps werden Einstellungen wie grpc.max_receive_message_length und grpc.max_send_message_length mit ChannelOption beim Konstruieren der Serverinstanz konfiguriert.

In ASP.NET Core stellt gRPC die Konfiguration über den Typ GrpcServiceOptions bereit. Beispielsweise kann die Maximalgröße für eingehende Nachrichten für einen gRPC-Dienst über AddGrpc konfiguriert werden. Im folgenden Beispiel wird der Standardwert für MaxReceiveMessageSize von 4 MB in 16 MB geändert:

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

Weitere Informationen zur Konfiguration finden Sie unter gRPC für .NET-Konfiguration.

Protokollierung

Bei C-core-basierten Apps wird mit GrpcEnvironmentdie Protokollierung für Debuggingzwecke konfiguriert. Im ASP.NET Core-Stapel wird diese Funktion über die Protokollierungs-API bereitgestellt. Beispielsweise kann Protokollierung über Konstruktorinjektion zum gRPC-Dienst hinzugefügt werden:

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

Weitere Informationen zur gRPC-Protokollierung und -Diagnose finden Sie unter Protokollierung und Diagnosen in gRPC für .NET.

HTTPS

Bei C-core-basierten Apps wird HTTPS über die Eigenschaft Server.Ports konfiguriert. Ein ähnliches Konzept wird beim Konfigurieren von Servern in ASP.NET Core verwendet. Kestrel verwendet beispielsweise die Endpunktkonfiguration für diese Funktion.

gRPC-Interceptors

ASP.NET Core-Middleware bietet ähnliche Funktionen wie Interceptors in C-core-basierten gRPC-Apps. Beide werden von gRPC-Apps in ASP.NET Core unterstützt, sodass es nicht notwendig ist, Interceptors neu zu schreiben.

Weitere Informationen zur Gegenüberstellung dieser Features finden Sie unter Vergleich von gRPC-Interceptors und Middleware.

Hosten von gRPC in Projekten ohne ASP.NET Core

Einem beliebigen Projekttyp kann ein C-Core-basierter Server hinzugefügt werden. gRPC für .NET-Server erfordert ASP.NET Core. ASP.NET Core ist in der Regel verfügbar, da die Projektdatei Microsoft.NET.SDK.Web als SDK angibt.

Ein gRPC-Server kann durch Hinzufügen von <FrameworkReference Include="Microsoft.AspNetCore.App" /> zu einem Projekt in Nicht-ASP.NET Core-Projekten gehostet werden. Die Frameworkreferenz stellt ASP.NET Core-APIs zur Verfügung und kann verwendet werden, um einen ASP.NET Core-Server zu starten.

Weitere Informationen finden Sie unter Hosten von gRPC in Projekten ohne ASP.NET Core.

Zusätzliche Ressourcen

• Übersicht für gRPC auf .NET
• gRPC-Dienste mit C#
• gRPC-Dienste mit ASP.NET Core
• Erstellen eines .NET Core-gRPC-Clients und -Servers in ASP.NET Core