Události
31. 3. 23 - 2. 4. 23
Ultimate Power BI, Fabric, SQL a AI community-led event. 31. března – 2. dubna. Použijte kód MSCUST pro slevu ve výši 150 USD. Ceny jdou nahoru 11. února.
Zaregistrovat se ještě dnesTento prohlížeč se už nepodporuje.
Upgradujte na Microsoft Edge, abyste mohli využívat nejnovější funkce, aktualizace zabezpečení a technickou podporu.
Poznámka
Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.
Upozornění
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.
Autor: James Newton-King
gRPC je vysoce výkonná architektura vzdáleného volání procedur (RPC). GRPC používá k vytváření vysoce výkonných služeb v reálném čase protokol HTTP/2, streamování, Protobuf a kontrakty zpráv.
Jedním omezením gRPC je, že ji nemůže používat každá platforma. Prohlížeče plně nepodporují protokol HTTP/2, takže REST rozhraní API a JSON jsou primárním způsobem, jak získat data do aplikací prohlížeče. Navzdory výhodám, které gRPC přináší, REST mají rozhraní API a JSON důležité místo v moderních aplikacích. Vytváření webových rozhraní API gRPC a JSON zvyšuje nežádoucí režii při vývoji aplikací.
Tento dokument popisuje, jak vytvořit webová rozhraní API JSON pomocí služeb gRPC.
gRPC JSON transkódování je rozšíření pro ASP.NET Core, které vytváří rozhraní RESTful JSON API pro služby gRPC. Po nakonfigurování transkódování umožňuje aplikacím volat služby gRPC se známými koncepty HTTP:
GRPC je stále možné použít k volání služeb.
Poznámka
Transkódování json gRPC nahrazuje rozhraní API HTTP gRPC, alternativní experimentální rozšíření.
Přidejte odkaz na balíček .Microsoft.AspNetCore.Grpc.JsonTranscoding
Zaregistrujte překódování v spouštěcím kódu serveru přidáním AddJsonTranscoding
: V Program.cs
souboru změňte builder.Services.AddGrpc();
na builder.Services.AddGrpc().AddJsonTranscoding();
.
Přidejte <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos>
do skupiny vlastností v souboru projektu (.csproj
):
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<InvariantGlobalization>true</InvariantGlobalization>
<IncludeHttpRuleProtos>true</IncludeHttpRuleProtos>
</PropertyGroup>
Anotace metod gRPC v .proto
souborech pomocí vazeb HTTP a tras:
syntax = "proto3";
option csharp_namespace = "GrpcServiceTranscoding";
import "google/api/annotations.proto";
package greet;
// The greeting service definition.
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply) {
option (google.api.http) = {
get: "/v1/greeter/{name}"
};
}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings.
message HelloReply {
string message = 1;
}
Metodu SayHello
gRPC teď můžete vyvolat jako gRPC a jako webové rozhraní API JSON:
GET /v1/greeter/world
{ "message": "Hello world" }
Pokud je server nakonfigurovaný tak, aby zapisoval protokoly pro každý požadavek, protokoly serveru ukazují, že služba gRPC provádí volání HTTP. Překódování mapuje příchozí požadavek HTTP na zprávu gRPC a převede zprávu odpovědi na JSON.
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/1.1 GET https://localhost:5001/v1/greeter/world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint 'gRPC - /v1/greeter/{name}'
info: Server.GreeterService[0]
Sending hello to world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
Executed endpoint 'gRPC - /v1/greeter/{name}'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 1.996ms 200 application/json
Metody gRPC musí být před podporou překódování opatřeny poznámkami s pravidlem HTTP. Pravidlo HTTP obsahuje informace o tom, jak volat metodu gRPC, například metodu HTTP a trasu.
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply) {
option (google.api.http) = {
get: "/v1/greeter/{name}"
};
}
}
Příklad pokračování:
Greeter
službu pomocí SayHello
metody. Metoda má zadané pravidlo HTTP pomocí názvu google.api.http
.GET
požadavky a trasou /v1/greeter/{name}
.name
zprávy požadavku je vázáno na parametr trasy.K dispozici je mnoho možností pro přizpůsobení způsobu, jakým metoda gRPC sváže rozhraní RESTful API. Další informace o přidávání poznámek metod gRPC a přizpůsobení FORMÁTU JSON najdete v tématu Konfigurace http a JSON pro transkódování json gRPC.
Tradiční gRPC přes HTTP/2 podporuje streamování ve všech směrech. Kódování je omezené jenom na streamování serveru. Streamování klientů a obousměrné metody streamování se nepodporují.
Metody streamování serveru používají JSON s oddělovači řádků. Každá zpráva napsaná pomocí WriteAsync
se serializuje do formátu JSON a za ní následuje nový řádek.
Následující metoda streamování serveru zapisuje tři zprávy:
public override async Task StreamingFromServer(ExampleRequest request,
IServerStreamWriter<ExampleResponse> responseStream, ServerCallContext context)
{
for (var i = 1; i <= 3; i++)
{
await responseStream.WriteAsync(new ExampleResponse { Text = $"Message {i}" });
await Task.Delay(TimeSpan.FromSeconds(1));
}
}
Klient obdrží tři objekty JSON s oddělovači řádků:
{"Text":"Message 1"}
{"Text":"Message 2"}
{"Text":"Message 3"}
Všimněte si, že WriteIndented
nastavení JSON se nevztahuje na metody streamování serveru. Při tisku se do FORMÁTU JSON přidávají nové řádky a prázdné znaky, které se nedají použít s json s oddělovači řádků.
Zobrazte nebo stáhněte ukázku transkódování a streamovací aplikace ASP.NET Core gPRC.
Šablona služby ASP.NET Core gRPC, která je součástí sady .NET SDK, vytvoří aplikaci, která je nakonfigurovaná jenom pro HTTP/2. Http/2 je dobrým výchozím nastavením, když aplikace podporuje pouze tradiční gRPC přes HTTP/2. Překódování ale funguje s HTTP/1.1 i HTTP/2. Některé platformy, jako je UPW nebo Unity, nemůžou používat PROTOKOL HTTP/2. Pokud chcete podporovat všechny klientské aplikace, nakonfigurujte server tak, aby povolil PROTOKOL HTTP/1.1 a HTTP/2.
Aktualizujte výchozí protokol v appsettings.json
:
{
"Kestrel": {
"EndpointDefaults": {
"Protocols": "Http1AndHttp2"
}
}
}
Případně nakonfigurujte Kestrel koncové body ve spouštěcím kódu.
Povolení protokolu HTTP/1.1 a HTTP/2 na stejném portu vyžaduje protokol TLS. Další informace o konfiguraci protokolů HTTP v aplikaci gRPC najdete v tématu ASP.NET Vyjednávání protokolu GRPC core.
Transkódování i gRPC-Web umožňují volat služby gRPC z prohlížeče. Způsob, jakým se ale každý z nich dělá, je jiný:
Předchozí Greeter
službu je možné volat pomocí javascriptových rozhraní API prohlížeče:
var name = nameInput.value;
fetch('/v1/greeter/' + name)
.then((response) => response.json())
.then((result) => {
console.log(result.message);
// Hello world
});
grpc-gateway je další technologie pro vytváření rozhraní RESTful JSON API ze služeb gRPC. Používá stejné .proto
poznámky k mapování konceptů HTTP na služby gRPC.
grpc-gateway používá generování kódu k vytvoření reverzního proxy serveru. Reverzní proxy překládá volání RESTful do gRPC+Protobuf a odesílá volání přes HTTP/2 do služby gRPC. Výhodou tohoto přístupu je, že služba gRPC neví o rozhraních RESTful JSON API. Každý server gRPC může používat grpc-gateway.
Mezitím se transkódování JSON gRPC spouští v aplikaci ASP.NET Core. Deserializuje JSON do zpráv Protobuf a pak přímo vyvolá službu gRPC. Překódování v ASP.NET Core nabízí vývojářům aplikací .NET výhody:
Informace o instalaci a použití brány grpc-gateway najdete v souboru README brány grpc.
gRPC je vysoce výkonná architektura vzdáleného volání procedur (RPC). GRPC používá k vytváření vysoce výkonných služeb v reálném čase protokol HTTP/2, streamování, Protobuf a kontrakty zpráv.
Jedním omezením gRPC je, že ji nemůže používat každá platforma. Prohlížeče plně nepodporují protokol HTTP/2, takže REST rozhraní API a JSON jsou primárním způsobem, jak získat data do aplikací prohlížeče. Navzdory výhodám, které gRPC přináší, REST mají rozhraní API a JSON důležité místo v moderních aplikacích. Vytváření webových rozhraní API gRPC a JSON zvyšuje nežádoucí režii při vývoji aplikací.
Tento dokument popisuje, jak vytvořit webová rozhraní API JSON pomocí služeb gRPC.
gRPC JSON transkódování je rozšíření pro ASP.NET Core, které vytváří rozhraní RESTful JSON API pro služby gRPC. Po nakonfigurování transkódování umožňuje aplikacím volat služby gRPC se známými koncepty HTTP:
GRPC je stále možné použít k volání služeb.
Poznámka
Transkódování json gRPC nahrazuje rozhraní API HTTP gRPC, alternativní experimentální rozšíření.
Microsoft.AspNetCore.Grpc.JsonTranscoding
AddJsonTranscoding
: V Program.cs
souboru změňte builder.Services.AddGrpc();
na builder.Services.AddGrpc().AddJsonTranscoding();
./google/api
v adresáři projektu, který soubor obsahuje .csproj
.google/api/http.proto
soubory google/api/annotations.proto
do /google/api
adresáře..proto
souborech pomocí vazeb HTTP a tras:syntax = "proto3";
option csharp_namespace = "GrpcServiceTranscoding";
import "google/api/annotations.proto";
package greet;
// The greeting service definition.
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply) {
option (google.api.http) = {
get: "/v1/greeter/{name}"
};
}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings.
message HelloReply {
string message = 1;
}
Metodu SayHello
gRPC teď můžete vyvolat jako gRPC a jako webové rozhraní API JSON:
GET /v1/greeter/world
{ "message": "Hello world" }
Pokud je server nakonfigurovaný tak, aby zapisoval protokoly pro každý požadavek, protokoly serveru ukazují, že služba gRPC provádí volání HTTP. Překódování mapuje příchozí požadavek HTTP na zprávu gRPC a převede zprávu odpovědi na JSON.
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/1.1 GET https://localhost:5001/v1/greeter/world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint 'gRPC - /v1/greeter/{name}'
info: Server.GreeterService[0]
Sending hello to world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
Executed endpoint 'gRPC - /v1/greeter/{name}'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 1.996ms 200 application/json
Metody gRPC musí být před podporou překódování opatřeny poznámkami s pravidlem HTTP. Pravidlo HTTP obsahuje informace o tom, jak volat metodu gRPC, například metodu HTTP a trasu.
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply) {
option (google.api.http) = {
get: "/v1/greeter/{name}"
};
}
}
Příklad pokračování:
Greeter
službu pomocí SayHello
metody. Metoda má zadané pravidlo HTTP pomocí názvu google.api.http
.GET
požadavky a trasou /v1/greeter/{name}
.name
zprávy požadavku je vázáno na parametr trasy.K dispozici je mnoho možností pro přizpůsobení způsobu, jakým metoda gRPC sváže rozhraní RESTful API. Další informace o přidávání poznámek metod gRPC a přizpůsobení FORMÁTU JSON najdete v tématu Konfigurace http a JSON pro transkódování json gRPC.
Tradiční gRPC přes HTTP/2 podporuje streamování ve všech směrech. Kódování je omezené jenom na streamování serveru. Streamování klientů a obousměrné metody streamování se nepodporují.
Metody streamování serveru používají JSON s oddělovači řádků. Každá zpráva napsaná pomocí WriteAsync
se serializuje do formátu JSON a za ní následuje nový řádek.
Následující metoda streamování serveru zapisuje tři zprávy:
public override async Task StreamingFromServer(ExampleRequest request,
IServerStreamWriter<ExampleResponse> responseStream, ServerCallContext context)
{
for (var i = 1; i <= 3; i++)
{
await responseStream.WriteAsync(new ExampleResponse { Text = $"Message {i}" });
await Task.Delay(TimeSpan.FromSeconds(1));
}
}
Klient obdrží tři objekty JSON s oddělovači řádků:
{"Text":"Message 1"}
{"Text":"Message 2"}
{"Text":"Message 3"}
Všimněte si, že WriteIndented
nastavení JSON se nevztahuje na metody streamování serveru. Při tisku se do FORMÁTU JSON přidávají nové řádky a prázdné znaky, které se nedají použít s json s oddělovači řádků.
Zobrazte nebo stáhněte ukázku transkódování a streamovací aplikace ASP.NET Core gPRC.
Šablona služby ASP.NET Core gRPC, která je součástí sady .NET SDK, vytvoří aplikaci, která je nakonfigurovaná jenom pro HTTP/2. Http/2 je dobrým výchozím nastavením, když aplikace podporuje pouze tradiční gRPC přes HTTP/2. Překódování ale funguje s HTTP/1.1 i HTTP/2. Některé platformy, jako je UPW nebo Unity, nemůžou používat PROTOKOL HTTP/2. Pokud chcete podporovat všechny klientské aplikace, nakonfigurujte server tak, aby povolil PROTOKOL HTTP/1.1 a HTTP/2.
Aktualizujte výchozí protokol v appsettings.json
:
{
"Kestrel": {
"EndpointDefaults": {
"Protocols": "Http1AndHttp2"
}
}
}
Případně nakonfigurujte Kestrel koncové body ve spouštěcím kódu.
Povolení protokolu HTTP/1.1 a HTTP/2 na stejném portu vyžaduje protokol TLS. Další informace o konfiguraci protokolů HTTP v aplikaci gRPC najdete v tématu ASP.NET Vyjednávání protokolu GRPC core.
Transkódování i gRPC-Web umožňují volat služby gRPC z prohlížeče. Způsob, jakým se ale každý z nich dělá, je jiný:
Předchozí Greeter
službu je možné volat pomocí javascriptových rozhraní API prohlížeče:
var name = nameInput.value;
fetch('/v1/greeter/' + name)
.then((response) => response.json())
.then((result) => {
console.log(result.message);
// Hello world
});
grpc-gateway je další technologie pro vytváření rozhraní RESTful JSON API ze služeb gRPC. Používá stejné .proto
poznámky k mapování konceptů HTTP na služby gRPC.
grpc-gateway používá generování kódu k vytvoření reverzního proxy serveru. Reverzní proxy překládá volání RESTful do gRPC+Protobuf a odesílá volání přes HTTP/2 do služby gRPC. Výhodou tohoto přístupu je, že služba gRPC neví o rozhraních RESTful JSON API. Každý server gRPC může používat grpc-gateway.
Mezitím se transkódování JSON gRPC spouští v aplikaci ASP.NET Core. Deserializuje JSON do zpráv Protobuf a pak přímo vyvolá službu gRPC. Překódování v ASP.NET Core nabízí vývojářům aplikací .NET výhody:
Informace o instalaci a použití brány grpc-gateway najdete v souboru README brány grpc.
Zpětná vazba k produktu ASP.NET Core
ASP.NET Core je open source projekt. Vyberte odkaz pro poskytnutí zpětné vazby:
Události
31. 3. 23 - 2. 4. 23
Ultimate Power BI, Fabric, SQL a AI community-led event. 31. března – 2. dubna. Použijte kód MSCUST pro slevu ve výši 150 USD. Ceny jdou nahoru 11. února.
Zaregistrovat se ještě dnesŠkolení
Postup výuky
Vytváření aplikací a služeb nativních pro cloud pomocí .NET a ASP.NET Core - Training
Vytvářejte nezávisle nasazovatelné, vysoce škálovatelné a odolné aplikace a služby pomocí bezplatné a opensourcové platformy .NET. S .NET můžete pro aplikace a služby .NET a ASP.NET Core používat oblíbenou technologii mikroslužeb, jako je Docker, Kubernetes, Dapr, Azure Container Registry a další.