gRPC-Dienste mit ASP.NET Core

In diesem Dokument wird gezeigt, wie Sie mit gRPC-Diensten unter Verwendung von ASP.NET Core die ersten Schritte unternehmen können.

Voraussetzungen

Visual Studio

• Visual Studio 2022 mit der Workload ASP.NET und Webentwicklung

  

Visual Studio Code

• Visual Studio Code
• C# für Visual Studio Code (neueste Version)
• .NET 8.0 SDK

In den Visual Studio Code-Anweisungen wird die .NET CLI für ASP.NET Core-Entwicklungsfunktionen wie die Projekterstellung verwendet. Sie können diese Schritte unter macOS, Linux oder Windows sowie in jedem beliebigen Code-Editor ausführen. Kleinere Änderungen sind möglicherweise erforderlich, wenn Sie ein anderes Programm als Visual Studio Code verwenden.

Visual Studio für Mac

• Visual Studio 2022 für Mac: Neueste Version

  Wichtig

  Microsoft hat die Ausmusterung von Visual Studio für Mac angekündigt. Visual Studio für Mac wird ab dem 31. August 2024 nicht mehr unterstützt. Zu den Alternativen gehören:

  • Visual Studio Code mit dem C#-Development-Kit und zugehörigen Erweiterungen, z. B. .NET MAUI und Unity.
  • Visual Studio-IDE, die unter Windows auf einer Mac-VM ausgeführt wird.
  • Visual Studio IDE, die unter Windows auf einer VM in der Cloud ausgeführt wird.

  Weitere Informationen finden Sie in der Ausmusterungsankündigung von Visual Studio für Mac.

Erste Schritte mit dem gRPC-Dienst in ASP.NET Core

Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).

Visual Studio

Ausführliche Informationen zum Erstellen eines gRPC-Projekts finden Sie unter Erste Schritte mit gRPC-Diensten.

Visual Studio Code / Visual Studio für Mac

Führen Sie dotnet new grpc -o GrpcGreeter über die Befehlszeile aus.

Hinzufügen von gRPC-Diensten zu einer ASP.NET Core-App

gRPC erfordert das Paket Grpc.AspNetCore.

Konfigurieren von gRPC

In Program.cs:

• gRPC wird mit der Methode AddGrpc aktiviert.
• Jeder gRPC-Dienst wird der Routingpipeline durch die MapGrpcService-Methode hinzugefügt.

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();

Wenn Sie möchten, dass Codekommentare in anderen Sprachen als Englisch angezeigt werden, informieren Sie uns in diesem GitHub-Issue.

ASP.NET Core-Middleware und -Features teilen sich die Routingpipeline, daher kann eine App so konfiguriert werden, dass sie zusätzliche Anforderungshandler bedient. Die zusätzlichen Anforderungshandler wie MVC-Controller arbeiten parallel zu den konfigurierten gRPC-Diensten.

Serveroptionen

gRPC-Dienste können von allen integrierten ASP.NET Core-Servern gehostet werden.

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

†Erfordert .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher.

Weitere Informationen zum Auswählen des richtigen Servers für eine ASP.NET Core-App finden Sie unter Webserverimplementierungen in ASP.NET Core.

Kestrel

Kestrel ist ein plattformübergreifender Webserver für ASP.NET Core. Kestrel legt den Fokus auf Hochleistungs- und Speichernutzung, verfügt jedoch nicht über einige der erweiterten Features in HTTP.sys wie die Portfreigabe.

Kestrel gRPC-Endpunkte:

• Erfordert HTTP/2.
• Sollte mit Transport Layer Security (TLS) gesichert werden.

HTTP/2

gRPC erfordert HTTP/2. gRPC für ASP.NET Core überprüft HttpRequest.Protocol zu HTTP/2.

Kestrelunterstützt HTTP/2 auf den meisten modernen Betriebssystemen. Kestrel-Endpunkte sind standardmäßig für die Unterstützung von HTTP/1.1- und HTTP/2-Verbindungen konfiguriert.

TLS

Die für gRPC verwendeten Kestrel-Endpunkte sollten mit TLS gesichert werden. In der Entwicklung wird ein mit TLS gesicherter Endpunkt automatisch bei https://localhost:5001 erstellt, wenn das ASP.NET Core-Entwicklungszertifikat vorhanden ist. Es ist keine Konfiguration erforderlich. Ein https-Präfix prüft, ob der Kestrel-Endpunkt TLS verwendet.

In der Produktion muss TLS explizit konfiguriert sein. Im folgenden appsettings.json -Beispiel wird ein mit TLS gesicherter HTTP/2-Endpunkt bereitgestellt:

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

Alternativ können Kestrel-Endpunkte in Program.cs konfiguriert werden:

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>");
    });
});

Weitere Informationen zum Aktivieren von TLS mit Kestrel finden Sie unter Kestrel-HTTPS-Endpunktkonfiguration.

Protokollaushandlung

TLS wird für mehr als nur die Sicherung der Kommunikation verwendet. Der TLS Application-Layer Protocol Negotiation (ALPN)-Handshake wird zur Aushandlung des Verbindungsprotokolls zwischen dem Client und dem Server verwendet, wenn ein Endpunkt mehrere Protokolle unterstützt. Diese Aushandlung bestimmt, ob die Verbindung HTTP/1.1 oder HTTP/2 verwendet.

Wenn ein HTTP/2-Endpunkt ohne TLS konfiguriert wird, muss bei diesem Endpunkt für ListenOptions.ProtocolsHttpProtocols.Http2 festgelegt werden. Ein Endpunkt mit mehreren Protokollen, z. B. HttpProtocols.Http1AndHttp2, kann ohne die TLS nicht verwendet werden, da keine Aushandlung erfolgt. Für alle Verbindungen zum ungesicherten Endpunkt wird standardmäßig HTTP/1.1 festgelegt, und gRPC-Aufrufe schlagen fehl.

Weitere Informationen zum Aktivieren von HTTP/2 und TLS mit Kestrel finden Sie unter Kestrel-Endpunktkonfiguration.

Hinweis

macOS unterstützt ASP.NET Core gRPC mit TLS vor .NET 8 nicht. Es ist eine zusätzliche Konfiguration erforderlich, um gRPC-Dienste unter macOS erfolgreich auszuführen, wenn .NET 7 oder früher verwendet wird. Weitere Informationen finden Sie unter ASP.NET Core gRPC-App kann unter macOS nicht gestartet werden.

IIS

IIS (Internet Information Services, Internetinformationsdienste) stellen einen flexiblen, sicheren und verwaltbaren Webserver für das Hosten von Web-Apps (einschließlich ASP.NET Core) dar. .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit IIS zu hosten.

IIS muss für die Verwendung von TLS und HTTP/2 konfiguriert sein. Weitere Informationen finden Sie unter Verwenden von ASP.NET Core mit HTTP/2 in IIS.

HTTP.sys

HTTP.sys ist ein Webserver für ASP.NET Core, der nur unter Windows ausgeführt werden kann. .NET 5 und Windows 11 Build 22000 oder Windows Server 2022 Build 20348 oder höher sind erforderlich, um gRPC-Dienste mit HTTP.sys zu hosten.

HTTP.sys muss für die Verwendung von TLS und HTTP/2 konfiguriert sein. Weitere Informationen finden Sie unter HTTP/2-Unterstützung des HTTP.sys-Webservers.

Hosten von gRPC in Projekten ohne ASP.NET Core

Ein ASP.NET Core-gRPC-Server wird normalerweise aus der gRPC-Vorlage erstellt. Die von der Vorlage erstellte Projektdatei verwendet 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>

Der Microsoft.NET.SDK.Web SDK-Wert fügt automatisch einen Verweis auf das ASP.NET Core-Framework hinzu. Der Verweis ermöglicht der App die Verwendung von ASP.NET Core-Typen, die zum Hosten eines Servers erforderlich sind.

Sie können einen gRPC-Server zu Projekten ohne ASP.NET Core mit den folgenden Projektdateieinstellungen hinzufügen:

<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>

Die obige Projektdatei:

• Verwendet nicht Microsoft.NET.SDK.Web als SDK.
• Fügt einen Frameworkverweis auf Microsoft.AspNetCore.App hinzu
  • Durch den Frameworkverweis können Apps, die nicht unter ASP.NET Core ausgeführt werden (z. B. Windows-Dienste, WPF-Apps oder WinForms-Apps), ASP.NET Core verwenden.
  • Die App kann jetzt ASP.NET Core-APIs verwenden, um einen ASP.NET Core-Server zu starten.
• Fügt gRPC-Anforderungen hinzu:
  • NuGet-Paketverweis auf Grpc.AspNetCore.
  • .proto-Datei.

Weitere Informationen zum Verwenden der Microsoft.AspNetCore.App-Frameworkreferenz finden Sie unter Verwenden des freigegebenen ASP.NET Core-Frameworks.

Integration mit ASP.NET Core-APIs

gRPC-Dienste haben vollen Zugriff auf die ASP.NET Core-Features wie Abhängigkeitsinjektion und Protokollierung. So kann die Dienstimplementierung z. B. einen Protokollierungsdienst aus dem Container der Abhängigkeitsinjektion über den Konstruktor auflösen:

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

Standardmäßig kann die gRPC-Dienstimplementierung andere Abhängigkeitsinjektionsdienste mit beliebiger Lebensdauer (Singleton, Bereichsbezogen oder Vorübergehend) auflösen.

Auflösen von HttpContext in gRPC-Methoden

Die gRPC-API bietet Zugriff auf einige HTTP/2-Nachrichtendaten, z. B. Methode, Host, Header und Nachspanne. Der Zugriff erfolgt über das Argument ServerCallContext, das an jede gRPC-Methode übergeben wird:

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

ServerCallContext bietet nicht in allen ASP.NET-APIs vollen Zugriff auf HttpContext. Die GetHttpContext-Erweiterungsmethode bietet vollen Zugriff auf HttpContext, das die zugrunde liegende HTTP/2-Nachricht in ASP.NET-APIs darstellt:

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
        });
    }
}

Zusätzliche Ressourcen

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