Služby gRPC s ASP.NET Core
Poznámka:
Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Upozorňující
Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Důležité
Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.
Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.
Požadavky
Sada Visual Studio 2022 se sadou funkcí Vývoj pro ASP.NET a web
Začínáme se službou gRPC v ASP.NET Core
Zobrazení nebo stažení vzorového kódu (postup stažení)
Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.
Přidání služeb gRPC do aplikace ASP.NET Core
Pro gRPC se vyžaduje balíček Grpc.AspNetCore.
Konfigurace gRPC
V Program.cs
:
- Metoda gRPC je povolená
AddGrpc
. - Každá služba gRPC se přidá do kanálu směrování prostřednictvím
MapGrpcService
metody.
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();
Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.
ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.
Možnosti serveru
Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.
- Kestrel
- TestServer
- IIS†
- HTTP.sys†
†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.
Kestrel
Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.
Kestrel Koncové body gRPC:
- Vyžaduje HTTP/2.
- Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).
HTTP/2
gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2
.
Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.
Protokol TLS
Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001
při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https
ověřuje, že Kestrel koncový bod používá protokol TLS.
V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json
příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:
{
"Kestrel": {
"Endpoints": {
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Protocols": "Http2",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
Alternativně Kestrel je možné nakonfigurovat koncové body v 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>");
});
});
Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.
Vyjednávání protokolu
Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.
Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2
hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2
je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.
Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.
Poznámka:
macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.
IIS
Internetová informační služba (IIS) je flexibilní, zabezpečený a spravovatelný webový server pro hostování webových aplikací, včetně ASP.NET Core. K hostování služeb gRPC ve službě IIS se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Služba IIS musí být nakonfigurovaná tak, aby používala protokol TLS a HTTP/2. Další informace naleznete v tématu Použití ASP.NET Core s HTTP/2 ve službě IIS.
HTTP.sys
HTTP.sys je webový server pro ASP.NET Core, který běží jenom ve Windows. K hostování služeb gRPC s HTTP.sys se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
HTTP.sys musí být nakonfigurované tak, aby používaly protokol TLS a HTTP/2. Další informace najdete v tématu HTTP.sys podpora HTTP/2 webového serveru.
Hostování gRPC v projektech non-ASP.NET Core
Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web
jako sada 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>
Microsoft.NET.SDK.Web
Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.
Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru projektu:
<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>
Předchozí soubor projektu:
- Nepoužívá
Microsoft.NET.SDK.Web
se jako sada SDK. - Přidá odkaz na architekturu do
Microsoft.AspNetCore.App
.- Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
- Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
- Přidá požadavky gRPC:
- Odkaz na balíček NuGet na
Grpc.AspNetCore
. .proto
soubor.
- Odkaz na balíček NuGet na
Další informace o použití referenční informace Microsoft.AspNetCore.App
k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.
Integrace s rozhraními API ASP.NET Core
Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).
Řešení httpContext v metodách gRPC
Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext
předaného každé metodě gRPC:
public class GreeterService : Greeter.GreeterBase
{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
ServerCallContext
neposkytuje úplný přístup ke HttpContext
všem rozhraním API ASP.NET. Metoda GetHttpContext
rozšíření poskytuje úplný přístup k HttpContext
reprezentaci základní zprávy HTTP/2 v rozhraních API ASP.NET:
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
});
}
}
Další materiály
Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.
Požadavky
Sada Visual Studio 2022 se sadou funkcí Vývoj pro ASP.NET a web
Začínáme se službou gRPC v ASP.NET Core
Zobrazení nebo stažení vzorového kódu (postup stažení)
Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.
Přidání služeb gRPC do aplikace ASP.NET Core
Pro gRPC se vyžaduje balíček Grpc.AspNetCore.
Konfigurace gRPC
V Program.cs
:
- Metoda gRPC je povolená
AddGrpc
. - Každá služba gRPC se přidá do kanálu směrování prostřednictvím
MapGrpcService
metody.
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();
Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.
ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.
Možnosti serveru
Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.
- Kestrel
- TestServer
- IIS†
- HTTP.sys†
†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.
Kestrel
Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.
Kestrel Koncové body gRPC:
- Vyžaduje HTTP/2.
- Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).
HTTP/2
gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2
.
Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.
Protokol TLS
Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001
při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https
ověřuje, že Kestrel koncový bod používá protokol TLS.
V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json
příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:
{
"Kestrel": {
"Endpoints": {
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Protocols": "Http2",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
Alternativně Kestrel je možné nakonfigurovat koncové body v 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>");
});
});
Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.
Vyjednávání protokolu
Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.
Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2
hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2
je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.
Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.
Poznámka:
macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.
IIS
Internetová informační služba (IIS) je flexibilní, zabezpečený a spravovatelný webový server pro hostování webových aplikací, včetně ASP.NET Core. K hostování služeb gRPC ve službě IIS se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Služba IIS musí být nakonfigurovaná tak, aby používala protokol TLS a HTTP/2. Další informace naleznete v tématu Použití ASP.NET Core s HTTP/2 ve službě IIS.
HTTP.sys
HTTP.sys je webový server pro ASP.NET Core, který běží jenom ve Windows. K hostování služeb gRPC s HTTP.sys se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
HTTP.sys musí být nakonfigurované tak, aby používaly protokol TLS a HTTP/2. Další informace najdete v tématu HTTP.sys podpora HTTP/2 webového serveru.
Hostování gRPC v projektech non-ASP.NET Core
Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web
jako sada 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>
Microsoft.NET.SDK.Web
Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.
Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru projektu:
<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>
Předchozí soubor projektu:
- Nepoužívá
Microsoft.NET.SDK.Web
se jako sada SDK. - Přidá odkaz na architekturu do
Microsoft.AspNetCore.App
.- Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
- Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
- Přidá požadavky gRPC:
- Odkaz na balíček NuGet na
Grpc.AspNetCore
. .proto
soubor.
- Odkaz na balíček NuGet na
Další informace o použití referenční informace Microsoft.AspNetCore.App
k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.
Integrace s rozhraními API ASP.NET Core
Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).
Řešení httpContext v metodách gRPC
Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext
předaného každé metodě gRPC:
public class GreeterService : Greeter.GreeterBase
{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
ServerCallContext
neposkytuje úplný přístup ke HttpContext
všem rozhraním API ASP.NET. Metoda GetHttpContext
rozšíření poskytuje úplný přístup k HttpContext
reprezentaci základní zprávy HTTP/2 v rozhraních API ASP.NET:
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
});
}
}
Další materiály
Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.
Požadavky
- Sada Visual Studio 2022 se sadou funkcí Vývoj pro ASP.NET a web
- Sada .NET 6.0 SDK
Začínáme se službou gRPC v ASP.NET Core
Zobrazení nebo stažení vzorového kódu (postup stažení)
Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.
Přidání služeb gRPC do aplikace ASP.NET Core
Pro gRPC se vyžaduje balíček Grpc.AspNetCore.
Konfigurace gRPC
V Program.cs
:
- Metoda gRPC je povolená
AddGrpc
. - Každá služba gRPC se přidá do kanálu směrování prostřednictvím
MapGrpcService
metody.
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();
Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.
ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.
Možnosti serveru
Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.
- Kestrel
- TestServer
- IIS†
- HTTP.sys†
†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.
Kestrel
Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.
Kestrel Koncové body gRPC:
- Vyžaduje HTTP/2.
- Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).
HTTP/2
gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2
.
Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.
Protokol TLS
Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001
při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https
ověřuje, že Kestrel koncový bod používá protokol TLS.
V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json
příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:
{
"Kestrel": {
"Endpoints": {
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Protocols": "Http2",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
Alternativně Kestrel je možné nakonfigurovat koncové body v 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>");
});
});
Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.
Vyjednávání protokolu
Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.
Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2
hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2
je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.
Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.
Poznámka:
macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.
IIS
Internetová informační služba (IIS) je flexibilní, zabezpečený a spravovatelný webový server pro hostování webových aplikací, včetně ASP.NET Core. K hostování služeb gRPC ve službě IIS se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Služba IIS musí být nakonfigurovaná tak, aby používala protokol TLS a HTTP/2. Další informace naleznete v tématu Použití ASP.NET Core s HTTP/2 ve službě IIS.
HTTP.sys
HTTP.sys je webový server pro ASP.NET Core, který běží jenom ve Windows. K hostování služeb gRPC s HTTP.sys se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
HTTP.sys musí být nakonfigurované tak, aby používaly protokol TLS a HTTP/2. Další informace najdete v tématu HTTP.sys podpora HTTP/2 webového serveru.
Hostování gRPC v projektech non-ASP.NET Core
Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web
jako sada 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>
Microsoft.NET.SDK.Web
Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.
Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru projektu:
<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>
Předchozí soubor projektu:
- Nepoužívá
Microsoft.NET.SDK.Web
se jako sada SDK. - Přidá odkaz na architekturu do
Microsoft.AspNetCore.App
.- Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
- Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
- Přidá požadavky gRPC:
- Odkaz na balíček NuGet na
Grpc.AspNetCore
. .proto
soubor.
- Odkaz na balíček NuGet na
Další informace o použití referenční informace Microsoft.AspNetCore.App
k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.
Integrace s rozhraními API ASP.NET Core
Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).
Řešení httpContext v metodách gRPC
Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext
předaného každé metodě gRPC:
public class GreeterService : Greeter.GreeterBase
{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
ServerCallContext
neposkytuje úplný přístup ke HttpContext
všem rozhraním API ASP.NET. Metoda GetHttpContext
rozšíření poskytuje úplný přístup k HttpContext
reprezentaci základní zprávy HTTP/2 v rozhraních API ASP.NET:
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
});
}
}
Další materiály
Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.
Požadavky
- Sada Visual Studio 2019 16.8 nebo novější se sadou funkcí Vývoj pro ASP.NET a web
- Sada .NET 5.0 SDK
Začínáme se službou gRPC v ASP.NET Core
Zobrazení nebo stažení vzorového kódu (postup stažení)
Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.
Přidání služeb gRPC do aplikace ASP.NET Core
Pro gRPC se vyžaduje balíček Grpc.AspNetCore.
Konfigurace gRPC
V Startup.cs
:
- Metoda gRPC je povolená
AddGrpc
. - Každá služba gRPC se přidá do kanálu směrování prostřednictvím
MapGrpcService
metody.
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>();
});
}
}
Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.
ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.
Možnosti serveru
Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.
- Kestrel
- TestServer
- IIS†
- HTTP.sys†
†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.
Kestrel
Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.
Kestrel Koncové body gRPC:
- Vyžaduje HTTP/2.
- Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).
HTTP/2
gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2
.
Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.
Protokol TLS
Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001
při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https
ověřuje, že Kestrel koncový bod používá protokol TLS.
V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json
příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:
{
"Kestrel": {
"Endpoints": {
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Protocols": "Http2",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
Alternativně Kestrel je možné nakonfigurovat koncové body v 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>();
});
Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.
Vyjednávání protokolu
Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.
Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2
hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2
je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.
Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.
Poznámka:
macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.
IIS
Internetová informační služba (IIS) je flexibilní, zabezpečený a spravovatelný webový server pro hostování webových aplikací, včetně ASP.NET Core. K hostování služeb gRPC ve službě IIS se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Služba IIS musí být nakonfigurovaná tak, aby používala protokol TLS a HTTP/2. Další informace naleznete v tématu Použití ASP.NET Core s HTTP/2 ve službě IIS.
HTTP.sys
HTTP.sys je webový server pro ASP.NET Core, který běží jenom ve Windows. K hostování služeb gRPC s HTTP.sys se vyžadují .NET 5 a Windows 11 Build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
HTTP.sys musí být nakonfigurované tak, aby používaly protokol TLS a HTTP/2. Další informace najdete v tématu HTTP.sys podpora HTTP/2 webového serveru.
Hostování gRPC v projektech non-ASP.NET Core
Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web
jako sada 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>
Microsoft.NET.SDK.Web
Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.
Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru projektu:
<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>
Předchozí soubor projektu:
- Nepoužívá
Microsoft.NET.SDK.Web
se jako sada SDK. - Přidá odkaz na architekturu do
Microsoft.AspNetCore.App
.- Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
- Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
- Přidá požadavky gRPC:
- Odkaz na balíček NuGet na
Grpc.AspNetCore
. .proto
soubor.
- Odkaz na balíček NuGet na
Další informace o použití referenční informace Microsoft.AspNetCore.App
k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.
Integrace s rozhraními API ASP.NET Core
Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).
Řešení httpContext v metodách gRPC
Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext
předaného každé metodě gRPC:
public class GreeterService : Greeter.GreeterBase
{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
ServerCallContext
neposkytuje úplný přístup ke HttpContext
všem rozhraním API ASP.NET. Metoda GetHttpContext
rozšíření poskytuje úplný přístup k HttpContext
reprezentaci základní zprávy HTTP/2 v rozhraních API ASP.NET:
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
});
}
}
Další materiály
Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.
Požadavky
- Sada Visual Studio 2019 16.4 nebo novější se sadou funkcí Vývoj pro ASP.NET a web
- Sada .NET Core 3.1 SDK
Začínáme se službou gRPC v ASP.NET Core
Zobrazení nebo stažení vzorového kódu (postup stažení)
Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.
Přidání služeb gRPC do aplikace ASP.NET Core
Pro gRPC se vyžaduje balíček Grpc.AspNetCore.
Konfigurace gRPC
V Startup.cs
:
- Metoda gRPC je povolená
AddGrpc
. - Každá služba gRPC se přidá do kanálu směrování prostřednictvím
MapGrpcService
metody.
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>();
});
}
}
Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.
ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.
Možnosti serveru
Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.
- Kestrel
- TestServer
- IIS†
- HTTP.sys†
†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.
Kestrel
Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.
Kestrel Koncové body gRPC:
- Vyžaduje HTTP/2.
- Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).
HTTP/2
gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2
.
Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.
Protokol TLS
Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001
při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https
ověřuje, že Kestrel koncový bod používá protokol TLS.
V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json
příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:
{
"Kestrel": {
"Endpoints": {
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Protocols": "Http2",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
Alternativně Kestrel je možné nakonfigurovat koncové body v 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>();
});
Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.
Vyjednávání protokolu
Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.
Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2
hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2
je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.
Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.
Poznámka:
macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.
Hostování gRPC v projektech non-ASP.NET Core
Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web
jako sada 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>
Microsoft.NET.SDK.Web
Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.
Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru projektu:
<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>
Předchozí soubor projektu:
- Nepoužívá
Microsoft.NET.SDK.Web
se jako sada SDK. - Přidá odkaz na architekturu do
Microsoft.AspNetCore.App
.- Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
- Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
- Přidá požadavky gRPC:
- Odkaz na balíček NuGet na
Grpc.AspNetCore
. .proto
soubor.
- Odkaz na balíček NuGet na
Další informace o použití referenční informace Microsoft.AspNetCore.App
k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.
Integrace s rozhraními API ASP.NET Core
Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).
Řešení httpContext v metodách gRPC
Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext
předaného každé metodě gRPC:
public class GreeterService : Greeter.GreeterBase
{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
ServerCallContext
neposkytuje úplný přístup ke HttpContext
všem rozhraním API ASP.NET. Metoda GetHttpContext
rozšíření poskytuje úplný přístup k HttpContext
reprezentaci základní zprávy HTTP/2 v rozhraních API ASP.NET:
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
});
}
}
Další materiály
Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.
Požadavky
- Visual Studio 2019 s úlohou vývoje pro ASP.NET a web
- .NET Core 3.0 SDK
Začínáme se službou gRPC v ASP.NET Core
Zobrazení nebo stažení vzorového kódu (postup stažení)
Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.
Přidání služeb gRPC do aplikace ASP.NET Core
Pro gRPC se vyžaduje balíček Grpc.AspNetCore.
Konfigurace gRPC
V Startup.cs
:
- Metoda gRPC je povolená
AddGrpc
. - Každá služba gRPC se přidá do kanálu směrování prostřednictvím
MapGrpcService
metody.
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>();
});
}
}
Pokud chcete zobrazit komentáře ke kódu přeložené do jiných jazyků, než je angličtina, dejte nám vědět v této diskuzi na GitHubu.
ASP.NET middlewaru Core a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny požadavků. Další obslužné rutiny žádostí, jako jsou kontrolery MVC, fungují paralelně s nakonfigurovanými službami gRPC.
Možnosti serveru
Služby gRPC můžou hostovat všechny integrované servery ASP.NET Core.
- Kestrel
- TestServer
- IIS†
- HTTP.sys†
†Požádejte si .NET 5 a Windows 11 build 22000 nebo Windows Server 2022 Build 20348 nebo novější.
Další informace o výběru správného serveru pro aplikaci ASP.NET Core najdete v tématu Implementace webového serveru v ASP.NET Core.
Kestrel
Kestrel je multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoké využití výkonu a paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.
Kestrel Koncové body gRPC:
- Vyžaduje HTTP/2.
- Měli byste být zabezpečeni pomocí protokolu TLS (Transport Layer Security).
HTTP/2
gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje , že httpRequest.Protocol je HTTP/2
.
Kestrelpodporuje PROTOKOL HTTP/2 ve většině moderních operačních systémů. Kestrel Koncové body jsou ve výchozím nastavení nakonfigurované tak, aby podporovaly připojení HTTP/1.1 a HTTP/2.
Protokol TLS
Kestrel koncové body používané pro gRPC by měly být zabezpečené pomocí protokolu TLS. Při vývoji se koncový bod zabezpečený protokolem TLS automaticky vytvoří https://localhost:5001
při přítomnosti vývojového certifikátu ASP.NET Core. Není nutná žádná konfigurace. Předpona https
ověřuje, že Kestrel koncový bod používá protokol TLS.
V produkčním prostředí musí být protokol TLS explicitně nakonfigurovaný. V následujícím appsettings.json
příkladu je k dispozici koncový bod HTTP/2 zabezpečený protokolem TLS:
{
"Kestrel": {
"Endpoints": {
"HttpsInlineCertFile": {
"Url": "https://localhost:5001",
"Protocols": "Http2",
"Certificate": {
"Path": "<path to .pfx file>",
"Password": "<certificate password>"
}
}
}
}
}
Alternativně Kestrel je možné nakonfigurovat koncové body v 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>();
});
Další informace o povolení protokolu TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu HTTPS.
Vyjednávání protokolu
Protokol TLS se používá pro více než zabezpečení komunikace. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá protokol HTTP/1.1 nebo HTTP/2.
Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2
hodnotu . Koncový bod s několika protokoly, jako HttpProtocols.Http1AndHttp2
je například, se nedá použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům ve výchozím nastavení http/1.1 a volání gRPC selžou.
Další informace o povolení protokolu HTTP/2 a TLS s Kestrelvyužitím najdete v tématu Kestrel Konfigurace koncového bodu.
Poznámka:
macOS nepodporuje ASP.NET Core gRPC s protokolem TLS před .NET 8. K úspěšnému spuštění služeb gRPC v systému macOS při použití rozhraní .NET 7 nebo starších se vyžaduje další konfigurace. Další informace najdete v tématu Nejde spustit aplikaci ASP.NET Core gRPC v systému macOS.
Hostování gRPC v projektech non-ASP.NET Core
Server ASP.NET Core gRPC se obvykle vytváří ze šablony gRPC. Soubor projektu vytvořený šablonou se používá Microsoft.NET.SDK.Web
jako sada 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>
Microsoft.NET.SDK.Web
Hodnota sady SDK automaticky přidá odkaz na architekturu ASP.NET Core. Odkaz umožňuje aplikaci používat typy ASP.NET Core vyžadované k hostování serveru.
Server gRPC můžete přidat do non-ASP.NET základních projektů s následujícím nastavením souboru projektu:
<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>
Předchozí soubor projektu:
- Nepoužívá
Microsoft.NET.SDK.Web
se jako sada SDK. - Přidá odkaz na architekturu do
Microsoft.AspNetCore.App
.- Referenční informace k architektuře umožňují non-ASP.NET základní aplikace, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat ASP.NET základní rozhraní API.
- Aplikace teď může ke spuštění serveru ASP.NET Core použít rozhraní API ASP.NET Core.
- Přidá požadavky gRPC:
- Odkaz na balíček NuGet na
Grpc.AspNetCore
. .proto
soubor.
- Odkaz na balíček NuGet na
Další informace o použití referenční informace Microsoft.AspNetCore.App
k rozhraní naleznete v tématu ASP.NET Core sdílené rozhraní.
Integrace s rozhraními API ASP.NET Core
Služby gRPC mají úplný přístup k funkcím ASP.NET Core, jako je injektáž závislostí (DI) a protokolování. Implementace služby může například přeložit službu protokolovacího nástroje z kontejneru DI prostřednictvím konstruktoru:
public class GreeterService : Greeter.GreeterBase
{
public GreeterService(ILogger<GreeterService> logger)
{
}
}
Ve výchozím nastavení může implementace služby gRPC vyřešit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).
Řešení httpContext v metodách gRPC
Rozhraní gRPC API poskytuje přístup k některým datům zpráv HTTP/2, jako je metoda, hostitel, hlavička a přívěsy. Access je prostřednictvím argumentu ServerCallContext
předaného každé metodě gRPC:
public class GreeterService : Greeter.GreeterBase
{
public override Task<HelloReply> SayHello(
HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
ServerCallContext
neposkytuje úplný přístup ke HttpContext
všem rozhraním API ASP.NET. Metoda GetHttpContext
rozšíření poskytuje úplný přístup k HttpContext
reprezentaci základní zprávy HTTP/2 v rozhraních API ASP.NET:
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
});
}
}