gRPC migreren van C-core naar gRPC voor .NET

Vanwege de implementatie van de onderliggende stack werken niet alle functies op dezelfde manier tussen op C-core gebaseerde gRPC--apps en gRPC voor .NET. In dit document worden de belangrijkste verschillen bij de migratie tussen de twee stacks belicht.

Belangrijk

gRPC C-core bevindt zich in de onderhoudsmodus en wordt afgeschaft ten gunste van gRPC voor .NET. gRPC C-core wordt niet aanbevolen voor nieuwe apps.

Platformondersteuning

gRPC C-core en gRPC voor .NET hebben verschillende platformondersteuning:

• gRPC C-core: een C++ gRPC-implementatie met eigen TLS- en HTTP/2-stacks. Het Grpc.Core-pakket is een .NET-wrapper rond gRPC C-core en bevat een gRPC-client en -server. Het ondersteunt .NET Framework, .NET Core en .NET 5 of hoger.
• gRPC voor .NET: ontworpen voor .NET Core 3.x en .NET 5 of hoger. Het maakt gebruik van TLS- en HTTP/2-stacks die zijn ingebouwd in moderne .NET-releases. Het Grpc.AspNetCore-pakket bevat een gRPC-server die wordt gehost in ASP.NET Core en waarvoor .NET Core 3.x of .NET 5 of hoger is vereist. Het Grpc.Net.Client-pakket bevat een gRPC-client. De client in Grpc.Net.Client heeft beperkte ondersteuning voor .NET Framework met behulp van WinHttpHandler.

Zie gRPC op .NET ondersteunde platformsvoor meer informatie.

Server en kanaal configureren

NuGet-pakketten, configuratie en opstartcode moeten worden gewijzigd bij het migreren van gRPC C-Core naar gRPC voor .NET.

gRPC voor .NET heeft afzonderlijke NuGet-pakketten voor de client en server. De toegevoegde pakketten zijn afhankelijk van of een app gRPC-services host of deze aanroept:

• Grpc.AspNetCore: Services worden gehost door ASP.NET Core. Zie gRPC-services met ASP.NET Corevoor informatie over serverconfiguratie.
• Grpc.Net.Client: clients gebruiken GrpcChannel, die intern netwerkfunctionaliteit gebruikt die is ingebouwd in .NET. Zie GRPC-services aanroepen met de .NET-clientvoor informatie over clientconfiguratie.

Wanneer de migratie is voltooid, moet het Grpc.Core-pakket worden verwijderd uit de app. Grpc.Core grote systeemeigen binaire bestanden bevat en het verwijderen van het pakket vermindert de hersteltijd en app-grootte van NuGet.

Door code gegenereerde services en clients

gRPC C-Core en gRPC voor .NET delen veel API's en code gegenereerd op basis van .proto bestanden is compatibel met beide gRPC-implementaties. De meeste clients en services kunnen zonder wijzigingen worden gemigreerd van C-Core naar gRPC voor .NET.

levensduur gRPC-service-implementatie

In de ASP.NET Core-stack worden gRPC-services standaard gemaakt met een levensduur. GRPC C-core wordt daarentegen standaard gekoppeld aan een service met een singleton-levensduur.

Met een begrensde levensduur kan de service-implementatie andere services met een begrensde levensduur aanroepen. Een levensduur binnen een bereik kan bijvoorbeeld ook DbContext van de DI-container oplossen via constructorinjectie. Gebruik maken van een beperkte levensduur

• Voor elke aanvraag wordt een nieuw exemplaar van de service-implementatie samengesteld.
• Het is niet mogelijk om toestand te delen tussen aanvragen via instantieleden van het implementatietype.
• De verwachting is om gedeelde statussen op te slaan in een singleton-service in de DI-container. De opgeslagen gedeelde statussen worden opgelost in de constructor van de gRPC-service-implementatie.

Zie Afhankelijkheidsinjectie in ASP.NET Corevoor meer informatie over de levensduur van de service.

Een singleton-service toevoegen

Om de overgang van een GRPC C-core-implementatie naar ASP.NET Core te vergemakkelijken, is het mogelijk om de levensduur van de service-implementatie te wijzigen van scoped in singleton. Dit omvat het toevoegen van een exemplaar van de service-implementatie aan de DI-container:

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

Een service-implementatie met een singleton-levensduur kan echter geen scoped services meer oplossen via constructorinjectie.

gRPC-services-opties configureren

In C-core-gebaseerde apps worden instellingen zoals grpc.max_receive_message_length en grpc.max_send_message_length geconfigureerd met ChannelOption wanneer het serverexemplaarwordt aangemaakt.

In ASP.NET Core biedt gRPC configuratie via het GrpcServiceOptions type. De maximale binnenkomende berichtgrootte van een gRPC-service kan bijvoorbeeld worden geconfigureerd via AddGrpc. In het volgende voorbeeld wordt de standaard-MaxReceiveMessageSize van 4 MB gewijzigd in 16 MB:

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

Zie gRPC voor .NET-configuratievoor meer informatie over configuratie.

Loggen

C-core-apps zijn afhankelijk van de GrpcEnvironment tot om de logboekregistratie- te configureren voor foutopsporingsdoeleinden. De ASP.NET Core-stack biedt deze functionaliteit via de Logging-API-. Een logger kan bijvoorbeeld worden toegevoegd aan de gRPC-service.

Constructorinjectie:

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

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

Primaire constructorinjectie (.NET 8 of hoger):

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

Zie Logboekregistratie en diagnostische gegevens in gRPC op .NETvoor meer informatie over gRPC-logboekregistratie en diagnostische gegevens.

HTTPS

C-core-apps configureren HTTPS via de eigenschap Server.Ports. Een vergelijkbaar concept wordt gebruikt voor het configureren van servers in ASP.NET Core. Kestrel gebruikt bijvoorbeeld eindpuntconfiguratie voor deze functionaliteit.

gRPC Interceptors

ASP.NET Core middleware biedt vergelijkbare functies in vergelijking met interceptors in GRPC-apps op basis van C-core. Beide worden ondersteund door ASP.NET Core gRPC-apps, dus het is niet nodig om interceptors opnieuw te schrijven.

Zie gRPC Interceptors versus Middlewarevoor meer informatie over hoe deze functies zich verhouden tot elkaar.

Host gRPC in non-ASP.NET Core-projecten

Een C-core-server kan worden toegevoegd aan elk projecttype. gRPC voor .NET-server vereist ASP.NET Core. ASP.NET Core is meestal beschikbaar omdat het projectbestand Microsoft.NET.SDK.Web opgeeft als de SDK.

Een gRPC-server kan worden gehost voor non-ASP.NET Core-projecten door <FrameworkReference Include="Microsoft.AspNetCore.App" /> toe te voegen aan een project. De frameworkreferentie maakt ASP.NET Core-API's beschikbaar en ze kunnen worden gebruikt om een ASP.NET Core-server te starten.

Zie Host gRPC in non-ASP.NET Core-projectenvoor meer informatie.

Aanvullende informatiebronnen

• overzicht van voor gRPC op .NET-
• gRPC-diensten met C#
• gRPC-services met ASP.NET Core
• Een .NET Core gRPC-client en -server maken in ASP.NET Core