gRPC-services met ASP.NET Core
Notitie
Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikelvoor de huidige release.
Waarschuwing
Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie de .NET- en .NET Core-ondersteuningsbeleidvoor meer informatie. Zie de .NET 9-versie van dit artikelvoor de huidige release.
Belangrijk
Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.
Zie de .NET 9-versie van dit artikelvoor de huidige release.
In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.
Voorwaarden
Visual Studio 2022 met de ASP.NET- en webontwikkelingsworkload.
Aan de slag met gRPC-service in ASP.NET Core
voorbeeldcode weergeven of downloaden (het downloaden van).
Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.
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/2
is.
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
- NuGet-pakketreferentie naar
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
In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.
Voorwaarden
Visual Studio 2022 met de ASP.NET- en webontwikkelingsworkload.
Aan de slag met gRPC-service in ASP.NET Core
Voorbeeldcode bekijken of downloaden (hoe te downloaden).
Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.
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 valideert dat HttpRequest.ProtocolHTTP/2
is.
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 webserver HTTP/2-ondersteuning.
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.
- NuGet-pakketreferentie naar
Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App
frameworkreferentie, zie Het gedeelde frameworkvan ASP.NET Core gebruiken.
Integratie met ASP.NET Core-API's
gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
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
, die 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
In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.
Voorwaarden
- Visual Studio 2022 met de ASP.NET- en webontwikkelingsworkload.
- .NET 6.0 SDK
Aan de slag met gRPC-service in ASP.NET Core
Voorbeeldcode bekijken of downloaden (hoe te downloaden).
Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.
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†
†Requires .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:
- Vereis HTTP/2.
- Moet worden beveiligd met TLS-(Transport Layer Security).
HTTP/2
gRPC vereist HTTP/2. gRPC voor ASP.NET Core valideert HttpRequest.Protocol is HTTP/2
.
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 webserver HTTP/2-ondersteuning.
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.
- NuGet-pakketreferentie naar
Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App
frameworkreferentie, zie Het gedeelde frameworkvan ASP.NET Core gebruiken.
Integratie met ASP.NET Core-API's
gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
Standaard kan de gRPC-service-implementatie andere DI-services met elke levensduur (Singleton, Scoped of Tijdelijk) resolveren.
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
, die 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
In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.
Voorwaarden
- Visual Studio 2019 16.8 of hoger met de ASP.NET- en webontwikkelingsworkload
- .NET 5.0 SDK
Aan de slag met gRPC-service in ASP.NET Core
voorbeeldcode weergeven of downloaden (hoe te downloaden).
Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.
gRPC-services toevoegen aan een ASP.NET Core-app
gRPC vereist het pakket Grpc.AspNetCore.
gRPC configureren
In Startup.cs
:
- gRPC is ingeschakeld met de methode
AddGrpc
. - Elke gRPC-service wordt via de
MapGrpcService
methode aan de routeringspijplijn toegevoegd.
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>();
});
}
}
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†
†Requires .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 valideert dat HttpRequest.Protocol is HTTP/2
.
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
:
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>();
});
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 webserver HTTP/2-ondersteuning.
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
. - Het
.proto
-bestand.
- NuGet-pakketreferentie naar
Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App
-frameworkreferentie, zie Het gebruik van het gedeelde framework van ASP.NET Core.
Integratie met ASP.NET Core-API's
gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
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
In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.
Voorwaarden
- Visual Studio 2019 16.4 of hoger met de ASP.NET- en webontwikkelingsworkload
- .NET Core 3.1 SDK
Aan de slag met gRPC-service in ASP.NET Core
voorbeeldcode weergeven of downloaden (hoe te downloaden).
Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.
gRPC-services toevoegen aan een ASP.NET Core-app
gRPC vereist het pakket Grpc.AspNetCore.
gRPC configureren
In Startup.cs
:
- gRPC is ingeschakeld met de methode
AddGrpc
. - Elke gRPC-service wordt via de
MapGrpcService
methode aan de routeringspijplijn toegevoegd.
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>();
});
}
}
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:
- Vereis HTTP/2.
- Moet worden beveiligd met TLS-(Transport Layer Security).
HTTP/2
gRPC vereist HTTP/2. gRPC voor ASP.NET Core valideert HttpRequest.Protocol is HTTP/2
.
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
:
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>();
});
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.
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.
- NuGet-pakketreferentie naar
Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App
frameworkreferentie, zie Gebruik het gedeelde framework van ASP.NET Core.
Integratie met ASP.NET Core-API's
gRPC-services hebben volledige toegang tot de ASP.NET Core-functies, zoals Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
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
die 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
In dit document ziet u hoe u aan de slag gaat met gRPC-services met behulp van ASP.NET Core.
Voorwaarden
- Visual Studio 2019- met de ASP.NET- en webontwikkelingsworkload
- .NET Core 3.0 SDK
Aan de slag met gRPC-service in ASP.NET Core
Voorbeeldcode bekijken of downloaden (hoe te downloaden).
Zie Aan de slag met gRPC-services voor gedetailleerde instructies over het maken van een gRPC-project.
gRPC-services toevoegen aan een ASP.NET Core-app
gRPC vereist het pakket Grpc.AspNetCore.
gRPC configureren
In Startup.cs
:
- gRPC is ingeschakeld met de methode
AddGrpc
. - Elke gRPC-service wordt via de
MapGrpcService
methode aan de routeringspijplijn toegevoegd.
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>();
});
}
}
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:
- Vereist HTTP/2.
- Moet worden beveiligd met TLS-(Transport Layer Security).
HTTP/2
gRPC vereist HTTP/2. gRPC voor ASP.NET Core valideert HttpRequest.Protocol is HTTP/2
.
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
:
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>();
});
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.
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.
- NuGet-pakketreferentie naar
Voor meer informatie over het gebruik van de Microsoft.AspNetCore.App
-referentie naar het framework, 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 Dependency Injection (DI) en Logging. De service-implementatie kan bijvoorbeeld een loggerservice van de DI-container oplossen via de constructor:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
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
die het onderliggende HTTP/2-bericht vertegenwoordigt in ASP.NET API's.
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
});
}
}