Služby gRPC s ASP.NET Core

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

Požadavky

Visual Studio

• Sada Visual Studio 2022 se sadou funkcí Vývoj pro ASP.NET a web

  

Visual Studio Code

• Visual Studio Code
• Jazyk C# pro Visual Studio Code (nejnovější verze)
• .NET 8.0 SDK

V pokynech pro Visual Studio Code se pro vývojové funkce ASP.NET Core, jako je vytvoření projektu, používá .NET CLI. Podle těchto pokynů můžete postupovat v systému macOS, Linux nebo Windows a v jakémkoli editoru kódu. Pokud použijete jiný editor než Visual Studio Code, možná budete muset provést menší změny.

Visual Studio pro Mac

• Visual Studio 2022 pro Mac (nejnovější verze)

  Důležité

  Společnost Microsoft oznámila vyřazení Visual Studio pro Mac. Visual Studio pro Mac již nebudou podporovány od 31. srpna 2024. Mezi alternativy patří:

  • Visual Studio Code se sadou C# Dev Kit a souvisejícími rozšířeními, jako například .NET MAUIUnity.
  • Integrované vývojové prostředí sady Visual Studio spuštěné ve Windows na virtuálním počítači na Macu
  • Integrované vývojové prostředí Visual Studio pracující na Windows v virtuálním počítači v cloudu.

  Další informace najdete v oznámení o ukončení podpory Visual Studio pro Mac.

Úvod do služby gRPC v ASP.NET Core

Zobrazení nebo stažení vzorového kódu (postup stažení)

Visual Studio

Podrobné pokyny k vytvoření projektu gRPC najdete v tématu Začínáme se službami gRPC.

Visual Studio Code / Visual Studio pro Mac

Na příkazovém řádku spusťte příkaz dotnet new grpc -o GrpcGreeter.

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

Pro gRPC se vyžaduje balíček Grpc.AspNetCore.

Konfigurujte gRPC

V Program.cs:

• gRPC je povoleno pomocí metody 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 funkcionality sdílejí kanál směrování, takže aplikaci lze nakonfigurovat na obsluhu dalších zpracování 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†

†Vyžaduje .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.

Kestrel podporuje 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ě je možné nakonfigurovat Kestrel 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 Kestrel naleznete v části 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 HttpProtocols.Http2 Koncový bod s několika protokoly, jako například HttpProtocols.Http1AndHttp2, nelze použít bez zabezpečení TLS, protože není možné žádné vyjednávání. Všechna připojení k nezabezpečeným koncovým bodům používají ve výchozím nastavení HTTP/1.1 a volání gRPC selžou.

Další informace o povolení protokolu HTTP/2 a TLS s Kestrel naleznete v tématu konfigurace koncového bodu Kestrel.

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 jako SDK.
• Přidá odkaz na framework do Microsoft.AspNetCore.App.
  • Referenční architektura umožňuje ne-ASP.NET Core aplikacím, jako jsou služby Windows, aplikace WPF nebo aplikace WinForms, používat rozhraní API ASP.NET Core.
  • 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.

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

Injektáž konstruktoru:

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;

    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }
}

Injektáž primárního konstruktoru (.NET 8 nebo novější):

public class GreeterService(ILogger<GreeterService> logger) : Greeter.GreeterBase
{
    ...
}

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 trailery. 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 rozšíření GetHttpContext poskytuje plný přístup k reprezentaci základní zprávy HTTP/2 v ASP.NET API.

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

• Vytvoření serveru a klienta .NET Core gRPC v ASP.NET Core
• Přehled gRPC v .NET
• Služby gRPC s C#
• Kestrel webový server v ASP.NET Core