Služby gRPC s ASP.NET Core

Článek
02/03/2023
10 min ke čtení

Tento dokument ukazuje, jak začít se službami gRPC pomocí ASP.NET Core.

Požadavky

Visual Studio 2019 se sadou funkcí ASP.NET a vývoj pro 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í)

Visual Studio
Visual Studio Code / Visual Studio pro Mac

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 Core middleware a funkce sdílejí kanál směrování, proto je možné aplikaci nakonfigurovat tak, aby obsluhovala další obslužné rutiny žádostí. Další obslužné rutiny požadavků, například řadiče MVC, pracují paralelně s nakonfigurovanými službami 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.

Možnosti serveru

Služby gRPC můžou hostovat všechny integrované ASP.NET Core servery.

Kestrel
TestServer
IIS†
HTTP.sys...

†IIS vyžaduje .NET 5 a Windows 10 build 20300.1000 nebo novější.
:HTTP.sys vyžaduje .NET 5 a Windows 10 build 19529 nebo novější.

Předchozí verze Windows 10 Build můžou vyžadovat použití buildu Windows Insider.

Další informace o výběru správného serveru pro ASP.NET Core aplikaci najdete v tématu Implementace webového serveru v ASP.NET Core.

Kestrel

Kestrelje multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoký výkon a využití paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

Vyžadovat HTTP/2.
Zabezpečení by mělo být pomocí protokolu TLS (Transport Layer Security).

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje 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.

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ří v https://localhost:5001 okamžiku, kdy je k dispozici ASP.NET Core vývojový certifikát. Není nutná žádná konfigurace. Předpona https ověří, ž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ý pomocí protokolu TLS:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Alternativně Kestrel je možné koncové body nakonfigurovat v Program.csnástroji :

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 Kestrelnajdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Protokol TLS se používá víc než jen k zabezpečení komunikace. Metoda handshake protokolu ALPN (Application-Layer Protocol Negotiation) protokolu TLS se používá k vyjednání protokolu připojení mezi klientem a serverem, pokud koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá 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.Http2hodnotu . Koncový bod s více protokoly, například HttpProtocols.Http1AndHttp2 , nejde použít bez protokolu TLS, protože neexistuje žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům mají výchozí hodnotu HTTP/1.1 a volání gRPC se nezdaří.

Další informace o povolení PROTOKOLŮ HTTP/2 a TLS s Kestrelnástrojem 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í .NET 7 nebo starších verzí 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 se službou IIS se vyžaduje .NET 5 a Windows 10 Build 20300.1000 nebo novější, což může vyžadovat použití buildu Windows Insider.

Služba IIS musí být nakonfigurovaná tak, aby používala protokoly TLS a HTTP/2. Další informace najdete 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žaduje .NET 5 a Windows 10 Build 19529 nebo novější, což může vyžadovat použití buildu Windows Insider.

HTTP.sys musí být nakonfigurované tak, aby používaly protokoly TLS a HTTP/2. Další informace najdete v tématu podpora http/2 webového serveruHTTP.sys.

Kestrel

Kestrelje multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoký výkon a využití paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

Vyžadovat HTTP/2.
Zabezpečení by mělo být pomocí protokolu TLS (Transport Layer Security).

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje httpRequest.Protocol je HTTP/2.

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ří v https://localhost:5001 okamžiku, kdy je k dispozici ASP.NET Core vývojový certifikát. 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é koncové body nakonfigurovat v Program.csnástroji :

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 Kestrelnajdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Protokol TLS se používá pro více než jen pro zabezpečení komunikace. Metodou handshake protokolu ALPN (Application-Layer Protocol Negotiate) tls se vyjednává protokol připojení mezi klientem a serverem, pokud koncový bod podporuje více protokolů. Toto vyjednávání určuje, jestli připojení používá 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.Http2hodnotu . 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 jsou ve výchozím nastavení HTTP/1.1 a volání gRPC selžou.

Další informace o povolení PROTOKOLŮ HTTP/2 a TLS s Kestrelnajdete 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 macOS při použití .NET 7 nebo starších verzí 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 se službou IIS se vyžadují .NET 5 a Windows 10 Build 20300.1000 nebo novější, což může vyžadovat použití buildu Windows Insider.

Služba IIS musí být nakonfigurovaná tak, aby používala protokoly TLS a HTTP/2. Další informace najdete 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žaduje .NET 5 a Windows 10 build 19529 nebo novější, což může vyžadovat použití buildu Windows Insider.

HTTP.sys musí být nakonfigurované tak, aby používaly protokoly TLS a HTTP/2. Další informace najdete v tématu podpora http/2 webového serveruHTTP.sys.

Kestrel

Kestrelje multiplatformní webový server pro ASP.NET Core. Kestrel zaměřuje se na vysoký výkon a využití paměti, ale nemá některé pokročilé funkce v HTTP.sys, jako je sdílení portů.

Kestrel Koncové body gRPC:

Vyžadovat HTTP/2.
Zabezpečení by mělo být pomocí protokolu TLS (Transport Layer Security).

HTTP/2

gRPC vyžaduje HTTP/2. gRPC pro ASP.NET Core ověřuje httpRequest.Protocol jako HTTP/2.

Kestrelpodporuje 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.

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ří v https://localhost:5001 okamžiku, kdy je k dispozici ASP.NET Core vývojový certifikát. 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é koncové body nakonfigurovat v Program.csnástroji :

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 Kestrelnajdete v tématu Kestrel Konfigurace koncového bodu HTTPS.

Vyjednávání protokolu

Pokud je koncový bod HTTP/2 nakonfigurovaný bez protokolu TLS, musí být parametr ListenOptions.Protocols koncového bodu nastavený na HttpProtocols.Http2hodnotu . 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 jsou ve výchozím nastavení HTTP/1.1 a volání gRPC selžou.

Další informace o povolení PROTOKOLŮ HTTP/2 a TLS s Kestrelnajdete v tématu Kestrel Konfigurace koncového bodu.

Poznámka

Integrace s rozhraními ASP.NET CORE API

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 vyřeš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 přeložit jiné služby DI s libovolnou životností (Singleton, Scoped nebo Transient).

Řešení potíží s HttpContextem v metodách gRPC

Rozhraní API gRPC poskytuje přístup k některým datům zpráv HTTP/2, jako jsou metoda, hostitel, hlavička a upoutávky. Přístup probíhá 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 všem rozhraním HttpContext API ASP.NET. Rozšiřující GetHttpContext metoda poskytuje úplný přístup k HttpContext podkladové zprávě 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
        });
    }
}

Služby gRPC s ASP.NET Core

Požadavky

Začínáme se službou gRPC v ASP.NET Core

Přidání služeb gRPC do aplikace ASP.NET Core

Konfigurace gRPC

Možnosti serveru

Kestrel

HTTP/2

TLS

Vyjednávání protokolu

IIS

HTTP.sys

Kestrel

HTTP/2

TLS

Vyjednávání protokolu

IIS

HTTP.sys

Kestrel

HTTP/2

TLS

Vyjednávání protokolu

Integrace s rozhraními ASP.NET CORE API

Řešení potíží s HttpContextem v metodách gRPC

Další materiály

Další materiály

Další materiály