gRPC-szolgáltatások a ASP.NET Core használatával

Ez a dokumentum bemutatja, hogyan kezdheti meg a gRPC-szolgáltatások használatát a ASP.NET Core használatával.

Prerequisites

Visual Studio

• Visual Studio 2022 az ASP.NET és webfejlesztési munkaállomással.

  

Visual Studio Code

• Visual Studio Code
• Visual Studio Code -hoz készült C# (legújabb verzió)
• .NET 8 SDK

A Visual Studio Code utasításai a .NET CLI-t használják ASP.NET alapvető fejlesztési függvényekhez, például a projekt létrehozásához. Ezeket az utasításokat macOS, Linux vagy Windows rendszeren és bármilyen kódszerkesztővel követheti. Kisebb módosításokra lehet szükség, ha nem a Visual Studio Code-ot használja.

A gRPC szolgáltatás használatának első lépései a ASP.NET Core-ban

Mintakód megtekintése vagy letöltése (hogyan lehet letölteni).

Visual Studio

A gRPC-projektek létrehozásának részletes útmutatását a gRPC-szolgáltatások első lépések című témakörben találja.

Visual Studio Code

Futtassa dotnet new grpc -o GrpcGreeter a parancssorból.

GRPC-szolgáltatások hozzáadása egy ASP.NET Core-alkalmazáshoz

A gRPC használatához a Grpc.AspNetCore csomag szükséges.

GRPC konfigurálása

A Program.cs:

• A gRPC engedélyezve van a AddGrpc metódussal.
• Minden gRPC-szolgáltatás hozzá lesz adva az útválasztási folyamathoz a MapGrpcService metóduson keresztül.

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();

Ha az angoltól eltérő nyelvekre lefordított kódmegjegyzéseket szeretne látni, tudassa velünk a ez GitHub vita-topic-ben.

ASP.NET Core köztes szoftver és funkciók megosztják az útválasztási folyamatot, ezért az alkalmazás konfigurálható további kéréskezelők kiszolgálására. A további kéréskezelők, például az MVC-vezérlők párhuzamosan működnek a konfigurált gRPC-szolgáltatásokkal.

Kiszolgálói beállítások

A gRPC-szolgáltatásokat az összes beépített ASP.NET Core-kiszolgáló üzemeltetheti.

• Kestrel
• TestServer
• IIS†
• HTTP.sys†

†Requires .NET 5 és Windows 11 Build 22000 vagy Windows Server 2022 Build 20348 vagy újabb.

A ASP.NET Core-alkalmazás megfelelő kiszolgálójának kiválasztásáról további információt ASP.NET Corewebkiszolgáló-implementációiban talál.

Kestrel

Kestrel ASP.NET Core platformfüggetlen webkiszolgálója. Kestrel a nagy teljesítményre és a memóriakihasználtságra összpontosít, de nem rendelkezik a HTTP.sys speciális funkcióival, például a portmegosztással.

Kestrel gRPC-végpontok:

• HTTP/2-t igényel.
• A Transport Layer Security (TLS)protokollal kell biztosítani.

HTTP/2

A gRPC http/2-t igényel. Az ASP.NET Core-hoz készült gRPC ellenőrzi, hogy a(z) HttpRequest.Protocol megfelelő-e HTTP/2.

Kestrel támogatja a HTTP/2 a legtöbb modern operációs rendszeren. Kestrel végpontok alapértelmezés szerint a HTTP/1.1 és HTTP/2 kapcsolatok támogatására vannak konfigurálva.

TLS

Kestrel gRPC-hez használt végpontokat TLS-lel kell védeni. A fejlesztés során a rendszer automatikusan létrehoz egy TLS-lel védett végpontot https://localhost:5001, amikor a ASP.NET Core fejlesztési tanúsítvány jelen van. Nincs szükség konfigurációra. Egy https előtag ellenőrzi, hogy a Kestrel végpont TLS-t használ-e.

Éles környezetben a TLS-t explicit módon kell konfigurálni. A következő appsettings.json példában egy TLS-lel védett HTTP/2-végpontot biztosítunk:

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

Másik lehetőségként Kestrel végpontok konfigurálhatók 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>");
    });
});

A TLS Kestrelvaló engedélyezéséről további információt a Kestrel HTTPS-végpont konfigurációról szólócímű cikkben talál.

Protokoll-egyeztetés

A TLS több mint a kommunikáció biztonságossá tételéhez használható. A TLS Application-Layer Protocol Negotiation (ALPN) kézfogás az ügyfél és a kiszolgáló közötti kapcsolati protokoll egyeztetésére szolgál, ha egy végpont több protokollt támogat. Ez a tárgyalás határozza meg, hogy a kapcsolat HTTP/1.1 vagy HTTP/2 protokollt használ-e.

Ha egy HTTP/2-végpont TLS nélkül van konfigurálva, a végpont ListenOptions.Protocols értékének HttpProtocols.Http2kell lennie. A több protokollt ( például HttpProtocols.Http1AndHttp2) tartalmazó végpont nem használható TLS nélkül, mert nincs egyeztetés. A nem biztonságos végponttal való minden kapcsolat alapértelmezés szerint HTTP/1.1, és a gRPC-hívások sikertelenek.

A HTTP/2 és a TLS a(z) Kestrelhasználatával történő engedélyezéséről további információt a(z) Kestrel végpont-konfigurációhoz tartozócímű cikkben talál.

Note

A macOS nem támogatja a ASP.NET Core gRPC-t a TLS-sel a .NET 8 előtt. További konfigurációra van szükség a gRPC-szolgáltatások macOS rendszeren történő sikeres futtatásához a .NET 7 vagy korábbi verziók használatakor. További információ: Nem indítható el ASP.NET Core gRPC-alkalmazás macOS.

IIS

Internet Information Services (IIS) egy rugalmas, biztonságos és kezelhető webkiszolgáló webalkalmazások üzemeltetéséhez, beleértve a ASP.NET Core-t is. A .NET 5 és a Windows 11 Build 22000 vagy Windows Server 2022 Build 20348 vagy újabb verziójára van szükség a gRPC-szolgáltatások IIS-vel való üzemeltetéséhez.

Az IIS-t TLS és HTTP/2 használatára kell konfigurálni. További információért lásd: Az ASP.NET Core használata HTTP/2-vel IIS-en.

HTTP.sys

HTTP.sys egy webkiszolgáló ASP.NET Core számára, amely csak Windows rendszeren fut. A .NET 5, a Windows 11 Build 22000 vagy a Windows Server 2022 Build 20348 vagy újabb verziójára van szükség a gRPC-szolgáltatások HTTP.sysvaló futtatásához.

HTTP.sys TLS és HTTP/2 használatára kell konfigurálni. További információ: HTTP.sys http/2 webkiszolgáló támogatása.

gRPC kiszolgálása nem-ASP.NET Core projektekben

A ASP.NET Core gRPC-kiszolgáló általában a gRPC-sablonból jön létre. A sablon által létrehozott projektfájl Microsoft.NET.SDK.Web használ SDK-ként:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

A Microsoft.NET.SDK.Web SDK-érték automatikusan hozzáad egy hivatkozást a ASP.NET Core-keretrendszerhez. A hivatkozás lehetővé teszi, hogy az alkalmazás a kiszolgáló üzemeltetéséhez szükséges ASP.NET Core-típusokat használja.

GRPC-kiszolgálót a következő projektfájl-beállításokkal adhat hozzá non-ASP.NET Core-projektekhez:

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

Az előző projektfájl:

• Nem használja Microsoft.NET.SDK.Web SDK-ként.
• Hozzáad egy keretrendszerhivatkozást a(z) Microsoft.AspNetCore.App-hoz.
  • A keretrendszer-referencia lehetővé teszi non-ASP.NET Core-alkalmazások, például a Windows-szolgáltatások, a WPF-alkalmazások vagy a WinForms-alkalmazások ASP.NET Core API-k használatát.
  • Az alkalmazás mostantól ASP.NET Core API-kkal indíthat ASP.NET Core-kiszolgálót.
• GRPC-követelményeket ad hozzá:
  • A NuGet-csomaghivatkozás Grpc.AspNetCore.
  • .proto fájl.

A Microsoft.AspNetCore.App keretrendszerreferenciájának használatáról további információt A ASP.NET Core megosztott keretrendszercímű témakörben talál.

Integráció ASP.NET Core API-kkal

A gRPC-szolgáltatások teljes hozzáféréssel rendelkeznek az ASP.NET Alapvető funkciókhoz, például függőséginjektálási (DI) és naplózási. A szolgáltatás implementációja például feloldhat egy naplózó szolgáltatást a DI-tárolóból.

Konstruktorinjektálás:

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

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

Elsődleges konstruktorinjektálás (.NET 8 vagy újabb):

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

A gRPC szolgáltatás implementációja alapértelmezés szerint bármilyen élettartammal feloldhat más DI-szolgáltatásokat (Singleton, Scoped vagy Transient).

HttpContext feloldása gRPC-metódusokban

A gRPC API hozzáférést biztosít néhány HTTP/2 üzenethez, például a metódushoz, a gazdagéphez, a fejléchez és a pótkocsikhoz. A hozzáférés az egyes gRPC-metódusok számára átadott ServerCallContext argumentumon keresztül történik:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext nem biztosít teljes hozzáférést HttpContext minden ASP.NET API-ban. A GetHttpContext bővítménymetódus teljes hozzáférést biztosít az ASP.NET API-kban a HTTP/2 üzenet alapját képező HttpContext-hez.

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
        });
    }
}

További erőforrások

• .NET gRPC-ügyfél és -kiszolgáló létrehozása a ASP.NET Core-ban
• .NET-alapú gRPC áttekintése
• gRPC-szolgáltatások C#-szal
• Kestrel webkiszolgáló ASP.NET Core