gRPC-services met ASP.NET Core

In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.

Voorwaarden

Visual Studio

• Visual Studio 2022 met de ASP.NET- en webontwikkelingsworkload.

  

Visual Studio Code

• Visual Studio Code
• C# voor Visual Studio Code (nieuwste versie)
• .NET 8.0 SDK-

De Visual Studio Code-instructies maken gebruik van de .NET CLI voor ASP.NET Core-ontwikkelfuncties, zoals het maken van een project. U kunt deze instructies volgen in macOS, Linux of Windows en met elke code-editor. Er zijn mogelijk kleine wijzigingen vereist als u iets anders dan Visual Studio Code gebruikt.

Visual Studio voor Mac-

• Visual Studio 2022 voor Mac (nieuwste versie)

  Belangrijk

  Microsoft heeft de buitengebruikstelling van Visual Studio voor Mac aangekondigd. Visual Studio voor Mac wordt vanaf 31 augustus 2024 niet meer ondersteund. Alternatieven zijn:

  • Visual Studio Code met de C# Dev Kit en gerelateerde extensies, zoals .NET MAUI en Unity.
  • Visual Studio IDE die wordt uitgevoerd in Windows op een VIRTUELE machine op mac.
  • Visual Studio IDE die wordt uitgevoerd in Windows op een VM in de cloud.

  Zie aankondiging van buitengebruikstelling van Visual Studio voor Macvoor meer informatie.

Aan de slag met gRPC-service in ASP.NET Core

voorbeeldcode weergeven of downloaden (het downloaden van).

Visual Studio

Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.

Visual Studio Code/Visual Studio voor Mac-

Voer dotnet new grpc -o GrpcGreeter uit vanaf de opdrachtregel.

gRPC-services toevoegen aan een ASP.NET Core-app

gRPC vereist het pakket Grpc.AspNetCore.

gRPC configureren

In Program.cs:

• gRPC is ingeschakeld met de methode AddGrpc.
• Elke gRPC-service wordt via de MapGrpcService methode aan de routeringspijplijn toegevoegd.

using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

Als u codeopmerkingen wilt zien die zijn vertaald naar andere talen dan Engels, laat het ons dan weten in dit GitHub-discussieprobleem.

ASP.NET Core middleware en -functies delen de routeringspijplijn. Daarom kan een app worden geconfigureerd voor extra aanvraaghandlers. De aanvullende aanvraaghandlers, zoals MVC-controllers, werken parallel met de geconfigureerde gRPC-services.

Serveropties

gRPC-services kunnen worden gehost door alle ingebouwde ASP.NET Core-servers.

• Kestrel
• TestServer
• IIS†
• HTTP.sys†

†Vereist .NET 5 en Windows 11 Build 22000, of Windows Server 2022 Build 20348 of hoger.

Zie webserver-implementaties in ASP.NET Core-voor meer informatie over het kiezen van de juiste server voor een ASP.NET Core-app.

Kestrel

Kestrel is een platformoverschrijdende webserver voor ASP.NET Core. Kestrel is gericht op hoge prestaties en geheugengebruik, maar heeft geen enkele van de geavanceerde functies in HTTP.sys, zoals het delen van poorten.

Kestrel gRPC-eindpunten:

• HTTP/2 vereisen.
• Moet worden beveiligd met TLS-(Transport Layer Security).

HTTP/2

gRPC vereist HTTP/2. gRPC voor ASP.NET Core controleert of HttpRequest.ProtocolHTTP/2is.

Kestrel ondersteunt HTTP/2- op de meeste moderne besturingssystemen. Kestrel eindpunten zijn standaard geconfigureerd ter ondersteuning van HTTP/1.1- en HTTP/2-verbindingen.

TLS

Kestrel eindpunten die worden gebruikt voor gRPC, moeten worden beveiligd met TLS. In ontwikkeling wordt automatisch een eindpunt gemaakt dat is beveiligd met TLS op https://localhost:5001 wanneer het ASP.NET Core-ontwikkelingscertificaat aanwezig is. Er is geen configuratie vereist. Een https voorvoegsel controleert of het Kestrel-eindpunt TLS gebruikt.

In productie moet TLS expliciet worden geconfigureerd. In het volgende appsettings.json voorbeeld wordt een HTTP/2-eindpunt dat is beveiligd met TLS opgegeven:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

U kunt ook Kestrel eindpunten configureren in Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Zie Kestrel https-eindpuntconfiguratievoor meer informatie over het inschakelen van TLS met Kestrel.

Protocolonderhandeling

TLS wordt gebruikt voor meer dan het beveiligen van communicatie. De ALPN -handshake (TLSApplication-Layer Protocol Negotiate) wordt gebruikt om te onderhandelen over het verbindingsprotocol tussen de client en de server wanneer een eindpunt meerdere protocollen ondersteunt. Deze onderhandeling bepaalt of de verbinding GEBRUIKMAAKT van HTTP/1.1 of HTTP/2.

Als een HTTP/2-eindpunt is geconfigureerd zonder TLS, moet het eindpunt ListenOptions.Protocols worden ingesteld op HttpProtocols.Http2. Een eindpunt met meerdere protocollen, zoals HttpProtocols.Http1AndHttp2, kan bijvoorbeeld niet worden gebruikt zonder TLS omdat er geen onderhandeling is. Alle verbindingen met het onbeveiligde eindpunt worden standaard ingesteld op HTTP/1.1 en gRPC-aanroepen mislukken.

Zie Kestrel eindpuntconfiguratievoor meer informatie over het inschakelen van HTTP/2 en TLS met Kestrel.

Notitie

macOS biedt geen ondersteuning voor ASP.NET Core gRPC met TLS vóór .NET 8. Aanvullende configuratie is vereist voor het uitvoeren van gRPC-services op macOS wanneer u .NET 7 of eerder gebruikt. Zie Kan ASP.NET Core gRPC-app niet starten op macOS-voor meer informatie.

IIS

IIS- (Internet Information Services) is een flexibele, veilige en beheerbare webserver voor het hosten van web-apps, waaronder ASP.NET Core. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met IIS.

IIS moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Zie Gebruik ASP.NET Core met HTTP/2 op IIS-voor meer informatie.

HTTP.sys

HTTP.sys is een webserver voor ASP.NET Core die alleen in Windows wordt uitgevoerd. .NET 5 en Windows 11 Build 22000 of Windows Server 2022 Build 20348 of hoger zijn vereist voor het hosten van gRPC-services met HTTP.sys.

HTTP.sys moet zijn geconfigureerd voor het gebruik van TLS en HTTP/2. Voor meer informatie, zie HTTP.sys webserverondersteuning HTTP/2.

Host gRPC in non-ASP.NET Core-projecten

Een ASP.NET Core gRPC-server wordt doorgaans gemaakt op basis van de gRPC-sjabloon. Het projectbestand dat door de sjabloon is gemaakt, gebruikt Microsoft.NET.SDK.Web als sdk:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

De Microsoft.NET.SDK.Web SDK-waarde voegt automatisch een verwijzing toe naar het ASP.NET Core-framework. Met de verwijzing kan de app gebruikmaken van ASP.NET Core-typen die zijn vereist voor het hosten van een server.

U kunt een gRPC-server toevoegen aan non-ASP.NET Core-projecten met de volgende projectbestandsinstellingen:

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Het voorgaande projectbestand:

• Maakt geen gebruik van Microsoft.NET.SDK.Web als sdk.
• Voegt een frameworkreferentie toe aan Microsoft.AspNetCore.App.
  • Met de frameworkreferentie kunnen non-ASP.NET Core-apps, zoals Windows Services, WPF-apps of WinForms-apps, ASP.NET Core-API's gebruiken.
  • De app kan nu ASP.NET Core-API's gebruiken om een ASP.NET Core-server te starten.
• Voegt gRPC-vereisten toe:
  • NuGet-pakketreferentie naar Grpc.AspNetCore.
  • .proto bestand

Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App frameworkreferentie, zie Gebruik het gedeelde frameworkvan ASP.NET Core.

Integratie met ASP.NET Core-API's

gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals afhankelijkheidsinjectie (DI) en logboekregistratie. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen.

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
{
    ...
}

Standaard kan de gRPC-service-implementatie andere DI-services oplossen met elke levensduur (Singleton, Scoped of Tijdelijk).

HttpContext in gRPC-methoden oplossen

De gRPC-API biedt toegang tot sommige HTTP/2-berichtgegevens, zoals de methode, host, header en trailers. Access wordt uitgevoerd via het ServerCallContext argument dat wordt doorgegeven aan elke gRPC-methode:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext biedt geen volledige toegang tot HttpContext in alle ASP.NET API's. De GetHttpContext-extensiemethode biedt volledige toegang tot de HttpContext dat het onderliggende HTTP/2-bericht in ASP.NET API's vertegenwoordigt.

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Aanvullende informatiebronnen

• Een .NET Core gRPC-client en -server maken in ASP.NET Core
• Overzicht voor gRPC op .NET
• gRPC-services met C#
• Kestrel webserver in ASP.NET Core