Služby gRPC s ASP.NET Core
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
});
}
}
Další materiály
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro