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 2022 mit der Workload ASP.NET und Webentwicklung
Erste Schritte mit dem gRPC-Dienst in ASP.NET Core
Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).
Ausführliche Informationen zum Erstellen eines gRPC-Projekts finden Sie unter Erste Schritte mit gRPC-Diensten.
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.
- NuGet-Paketverweis auf
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
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 2022 mit der Workload ASP.NET und Webentwicklung
Erste Schritte mit dem gRPC-Dienst in ASP.NET Core
Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).
Ausführliche Informationen zum Erstellen eines gRPC-Projekts finden Sie unter Erste Schritte mit gRPC-Diensten.
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.
- NuGet-Paketverweis auf
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
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 2022 mit der Workload ASP.NET und Webentwicklung
- .NET 6.0 SDK
Erste Schritte mit dem gRPC-Dienst in ASP.NET Core
Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).
Ausführliche Informationen zum Erstellen eines gRPC-Projekts finden Sie unter Erste Schritte mit gRPC-Diensten.
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.
- NuGet-Paketverweis auf
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
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 2019 Version 16.8 oder höher mit der Workload ASP.NET und Webentwicklung
- .NET 5.0 SDK
Erste Schritte mit dem gRPC-Dienst in ASP.NET Core
Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).
Ausführliche Informationen zum Erstellen eines gRPC-Projekts finden Sie unter Erste Schritte mit gRPC-Diensten.
Hinzufügen von gRPC-Diensten zu einer ASP.NET Core-App
gRPC erfordert das Paket Grpc.AspNetCore.
Konfigurieren von gRPC
In Startup.cs
:
- gRPC wird mit der Methode
AddGrpc
aktiviert. - Jeder gRPC-Dienst wird der Routingpipeline durch die
MapGrpcService
-Methode hinzugefügt.
public class Startup
{
// This method gets called by the runtime. Use this method to add services to the container.
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
services.AddGrpc();
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseRouting();
app.UseEndpoints(endpoints =>
{
// 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
endpoints.MapGrpcService<GreeterService>();
});
}
}
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:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.ConfigureKestrel(options =>
{
options.Listen(IPAddress.Any, 5001, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http2;
listenOptions.UseHttps("<path to .pfx file>",
"<certificate password>");
});
});
webBuilder.UseStartup<Startup>();
});
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.
- NuGet-Paketverweis auf
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
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 2019 Version 16.4 oder höher mit der Workload ASP.NET und Webentwicklung.
- .NET Core 3.1 SDK
Erste Schritte mit dem gRPC-Dienst in ASP.NET Core
Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).
Ausführliche Informationen zum Erstellen eines gRPC-Projekts finden Sie unter Erste Schritte mit gRPC-Diensten.
Hinzufügen von gRPC-Diensten zu einer ASP.NET Core-App
gRPC erfordert das Paket Grpc.AspNetCore.
Konfigurieren von gRPC
In Startup.cs
:
- gRPC wird mit der Methode
AddGrpc
aktiviert. - Jeder gRPC-Dienst wird der Routingpipeline durch die
MapGrpcService
-Methode hinzugefügt.
public class Startup
{
// This method gets called by the runtime. Use this method to add services to the container.
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
services.AddGrpc();
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseRouting();
app.UseEndpoints(endpoints =>
{
// 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
endpoints.MapGrpcService<GreeterService>();
});
}
}
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:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.ConfigureKestrel(options =>
{
options.Listen(IPAddress.Any, 5001, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http2;
listenOptions.UseHttps("<path to .pfx file>",
"<certificate password>");
});
});
webBuilder.UseStartup<Startup>();
});
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.
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.
- NuGet-Paketverweis auf
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
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 2019 mit der Workload ASP.NET- und Webentwicklung
- .NET Core 3.0 SDK
Erste Schritte mit dem gRPC-Dienst in ASP.NET Core
Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).
Ausführliche Informationen zum Erstellen eines gRPC-Projekts finden Sie unter Erste Schritte mit gRPC-Diensten.
Hinzufügen von gRPC-Diensten zu einer ASP.NET Core-App
gRPC erfordert das Paket Grpc.AspNetCore.
Konfigurieren von gRPC
In Startup.cs
:
- gRPC wird mit der Methode
AddGrpc
aktiviert. - Jeder gRPC-Dienst wird der Routingpipeline durch die
MapGrpcService
-Methode hinzugefügt.
public class Startup
{
// This method gets called by the runtime. Use this method to add services to the container.
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
services.AddGrpc();
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseRouting();
app.UseEndpoints(endpoints =>
{
// 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
endpoints.MapGrpcService<GreeterService>();
});
}
}
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:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.ConfigureKestrel(options =>
{
options.Listen(IPAddress.Any, 5001, listenOptions =>
{
listenOptions.Protocols = HttpProtocols.Http2;
listenOptions.UseHttps("<path to .pfx file>",
"<certificate password>");
});
});
webBuilder.UseStartup<Startup>();
});
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.
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.
- NuGet-Paketverweis auf
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
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für