Megosztás a következőn keresztül:

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

  • Cikk

Jegyzet

Ez nem a cikk legújabb verziója. Az aktuális kiadást lásd a cikk .NET 9-es verziójában.

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információ: .NET és .NET Core támogatási szabályzat. Az aktuális kiadásért lásd a cikk .NET 9-es verzióját.

Fontos

Ezek az információk egy olyan előzetes termékre vonatkoznak, amelyet a kereskedelmi forgalomba kerülés előtt jelentősen módosíthatnak. A Microsoft nem vállal kifejezett vagy hallgatólagos szavatosságot az itt megadott információkra vonatkozóan.

Az aktuális verzió megtekintéséhez lásd a jelen cikk .NET 9-es verzióját.

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

Előfeltételek

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

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.

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
  • Teszt Szerver
  • 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

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.

Jegyzet

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

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

Előfeltételek

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 kell letölteni).

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.

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 szeretné, hogy a kódhozzászólásokat angolon kívüli nyelvekre is lefordítsuk, jelezze nekünk a GitHub vitatémája alatt.

A ASP.NET Core middleware és funkciók osztoznak az útválasztási csatornán, ezért egy 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
  • Tesztkiszolgáló
  • 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

A gRPC http/2-t igényel. Az ASP.NET Core-hoz készült gRPC ellenőrzi, hogy HttpRequest.ProtocolHTTP/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>"
        }
      }
    }
  }
}

Alternatívaként Kestrel végpontok konfigurálhatók a Program.cs-ben:

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 Kestrelengedélyezéséről további információt a Kestrel HTTPS-végpont konfigurációcímű részben 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, akkor a végpont ListenOptions.ProtocolsHttpProtocols.Http2be kell állítani. 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 Kestrelvaló engedélyezéséről további információt Kestrel végpontkonfigurációscímű cikkben talál.

Jegyzet

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 az IIS-en.

HTTP.sys

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

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ás 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 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 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 Core szolgáltatásokhoz, például a függőséginjektálás (DI) és naplózás. A szolgáltatás implementációja például feloldhat egy naplózó szolgáltatást a DI-tárolóból a konstruktoron keresztül:

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

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 üzenet adatához, például a metódushoz, a gazdagéphez, a fejléchez és a lezáró fejlécekhez. 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 alapul szolgáló HTTP/2 üzenetet képviselő HttpContext-hez az ASP.NET API-kban.

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

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

Előfeltételek

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 tölthető le).

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.

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 szeretné, hogy a kódmegjegyzések angolon kívüli nyelvekre is le legyenek fordítva, jelezze nekünk a GitHub vitaindítójában .

ASP.NET Alapvető köztes szoftver és funkciók osztoznak az útválasztási folyamaton, ezért egy 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
  • TesztSzerver
  • 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

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

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

További információért a TLS Kestrelengedélyezéséről lásd a Kestrel HTTPS-végpont konfigurációt.

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.ProtocolsHttpProtocols.Http2kell beállítani. 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 Kestrelvaló engedélyezéséről további információt Kestrel végpontkonfigurációscímű cikkben talál.

Jegyzet

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ókért lásd: Az ASP.NET Core használata HTTP/2-vel az IIS.

HTTP.sys

HTTP.sys egy webkiszolgáló ASP.NET Core számára, amely csak Windows rendszeren fut. A .NET 5 és a Windows 11 Build 22000 vagy a Windows Server 2022 Build 20348 vagy újabb verzió szükséges a gRPC-szolgáltatások HTTP.syskiszolgálá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 hosztolása nem ASP.NET Core projekteken kívül

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 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 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 a konstruktoron keresztül:

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

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 üzenet adatához, például a metódushoz, a hosthoz, a fejléchez és az utótagokhoz. 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 körű hozzáférést biztosít az alapul szolgáló HTTP/2 üzenetet képviselő HttpContext-hez az ASP.NET API-kban.

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

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

Előfeltételek

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 (a letöltés módja).

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.

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 Startup.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.
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>();
        });
    }
}

Ha szeretné látni, hogy a kódkommentárok angolon kívüli nyelvekre is le legyenek fordítva, jelezze ezt nekünk a GitHub vitafórumánakszámú témájában.

ASP.NET Alapvető köztes szoftver és funkciók osztoznak az útválasztási folyamaton, ezért egy 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
  • TesztServer
  • 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

A gRPC http/2-t igényel. A ASP.NET Core-hoz készült gRPC ellenőrzi, HttpRequest.ProtocolHTTP/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>"
        }
      }
    }
  }
}

Alternatív megoldásként a Kestrel végpontok a Program.cs-ben konfigurálhatók.

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

A TLS Kestrelvaló engedélyezéséről további információt Kestrel HTTPS-végpont konfigurációscí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.ProtocolsHttpProtocols.Http2kell hogy legyen beállítva. 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 Kestrelvaló engedélyezéséről további információt Kestrel végpontkonfigurációscímű cikkben talál.

Jegyzet

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ó: ASP.NET Core használata HTTP/2-vel az IIS.

HTTP.sys

HTTP.sys egy webkiszolgáló ASP.NET Core számára, amely csak Windows rendszeren fut. A .NET 5 és 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.sysfuttatá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 hostolá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 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 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 a konstruktoron keresztül:

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

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 üzenetadatához, például a metódushoz, a gazdagéphez, a fejléchez és az utóiratokhoz. 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 minden ASP.NET API-hoz HttpContext-ben. A GetHttpContext bővítménymetódus teljes hozzáférést biztosít az ASP.NET API-kban a HttpContext-re, amely az alapul szolgáló HTTP/2 üzenetet képviseli.

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

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

Előfeltételek

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 kell letölteni).

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.

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 Startup.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.
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>();
        });
    }
}

Ha angoltól eltérő nyelvekre lefordított kódsorok megjegyzéseit szeretné látni, jelezze számunkra a GitHub vitafórumának .

ASP.NET Alapvető köztes szoftver és funkciók osztoznak az útválasztási folyamaton, ezért egy 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
  • TesztSzerver
  • 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

A gRPC http/2-t igényel. Az ASP.NET Core-hoz készült gRPC ellenőrzi, hogy a HttpRequest.Protocol érvényes-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ás lehetőségként a Kestrel végpontok konfigurálhatók a 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>();
        });

A TLS Kestrelvaló engedélyezéséről további információt Kestrel HTTPS-végpont konfigurációscí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.ProtocolsHttpProtocols.Http2kell beállítani. 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.

További információért a HTTP/2 és a TLS Kestrelvaló engedélyezéséről tekintse meg a Kestrel végpont konfigurációja című cikket.

Jegyzet

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.

gRPC szolgáltatás üzemeltetése 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 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 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 Core funkciókhoz, mint a Függőséginjektálás (DI) és a Naplózás. A szolgáltatás implementációja például feloldhat egy naplózó szolgáltatást a DI-tárolóból a konstruktoron keresztül:

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

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 üzenetadatához, például a metódushoz, a kiszolgálóhoz, a fejléchez és az utótagokhoz. 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énymódszer teljes hozzáférést biztosít az ASP.NET API-kban az alapul szolgáló HTTP/2 üzenetet képviselő 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

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

Előfeltételek

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

A mintakód megtekintése vagy letöltése (hogyan töltsük le).

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.

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 Startup.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.
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>();
        });
    }
}

Ha szeretné tudatni velünk, hogy angoltól eltérő nyelvekre is szeretné látni a kódjegyzeteket lefordítva, jelezze ezt a GitHub vitafórum témában.

ASP.NET Core köztes réteg és funkciók megosztják az útválasztási folyamatot, ezért egy alkalmazás konfigurálható további kéréskezelők kiszolgálása érdekében. 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
  • TesztSzerver
  • 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

A gRPC http/2-t igényel. A ASP.NET Core-hoz készült gRPC ellenőrzi, HttpRequest.ProtocolHTTP/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>"
        }
      }
    }
  }
}

Alternatívaként Kestrel végpontok konfigurálhatók Program.cs-ban.

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

A TLS Kestrelvaló engedélyezéséről további információt Kestrel HTTPS-végpont konfigurációscí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 -ját HttpProtocols.Http2kell beállítani. 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 TLS engedélyezéséről Kestrelhasználatával további információt a Kestrel végpont konfigurációscímű cikkben talál.

Jegyzet

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.

gRPC hosztolása ASP.NET Core-on kívüli 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 keretrendszer-hivatkozást a 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 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 Core funkciókhoz, mint például a Függőséginjektálás (DI) és a Naplózás. A szolgáltatás implementációja például feloldhat egy naplózó szolgáltatást a DI-tárolóból a konstruktoron keresztül:

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

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 üzenetadatokhoz, például a metódushoz, a gazdagéphez, a fejléchez és a végjelzőkhöz. 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 esetén minden ASP.NET API-ban. A GetHttpContext bővítménymetódus teljes hozzáférést biztosít az ASP.NET API-kban képviselt alapul szolgáló HTTP/2 üzenethez, amelyet a HttpContext képvisel.

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