Bagikan melalui

Layanan gRPC dengan ASP.NET Core

  • Artikel

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Dokumen ini menunjukkan cara memulai layanan gRPC menggunakan ASP.NET Core.

Prasyarat

Mulai menggunakan layanan gRPC di ASP.NET Core

Lihat atau unduh sampel kode (cara mengunduh).

Lihat Mulai menggunakan layanan gRPC untuk instruksi terperinci tentang cara membuat proyek gRPC.

Menambahkan layanan gRPC ke aplikasi ASP.NET Core

gRPC memerlukan paket Grpc.AspNetCore.

Mengonfigurasi gRPC

Di Program.cs:

  • gRPC diaktifkan dengan AddGrpc metode .
  • Setiap layanan gRPC ditambahkan ke alur perutean melalui MapGrpcService metode .
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();

Jika Anda ingin melihat komentar kode yang diterjemahkan ke bahasa selain bahasa Inggris, beri tahu kami dalam masalah diskusi GitHub ini.

ASP.NET Middleware core dan fitur berbagi alur perutean, oleh karena itu aplikasi dapat dikonfigurasi untuk melayani penangan permintaan tambahan. Penangan permintaan tambahan, seperti pengontrol MVC, bekerja secara paralel dengan layanan gRPC yang dikonfigurasi.

Opsi server

Layanan gRPC dapat dihosting oleh semua server ASP.NET Core bawaan.

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

†Requires .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru.

Untuk informasi selengkapnya tentang memilih server yang tepat untuk aplikasi ASP.NET Core, lihat Implementasi server web di ASP.NET Core.

Kestrel

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel berfokus pada performa tinggi dan pemanfaatan memori, tetapi tidak memiliki beberapa fitur canggih dalam HTTP.sys seperti berbagi port.

Kestrel Titik akhir gRPC:

HTTP/2

gRPC memerlukan HTTP/2. gRPC untuk ASP.NET Core memvalidasi HttpRequest.Protocol adalah HTTP/2.

Kestrelmendukung HTTP/2 pada sebagian besar sistem operasi modern. Kestrel titik akhir dikonfigurasi untuk mendukung koneksi HTTP/1.1 dan HTTP/2 secara default.

TLS

Kestrel titik akhir yang digunakan untuk gRPC harus diamankan dengan TLS. Dalam pengembangan, titik akhir yang diamankan dengan TLS secara otomatis dibuat https://localhost:5001 pada saat sertifikat pengembangan ASP.NET Core ada. Tidak diperlukan konfigurasi. Awalan https Kestrel memverifikasi titik akhir menggunakan TLS.

Dalam produksi, TLS harus dikonfigurasi secara eksplisit. Dalam contoh berikut appsettings.json , titik akhir HTTP/2 yang diamankan dengan TLS disediakan:

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

Atau, Kestrel titik akhir dapat dikonfigurasi di 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>");
    });
});

Untuk informasi selengkapnya tentang mengaktifkan TLS dengan Kestrel, lihat Kestrel Konfigurasi titik akhir HTTPS.

Negosiasi protokol

TLS digunakan untuk lebih dari mengamankan komunikasi. Jabat tangan TLS Application-Layer Protocol Negotiation (ALPN) digunakan untuk menegosiasikan protokol koneksi antara klien dan server ketika titik akhir mendukung beberapa protokol. Negosiasi ini menentukan apakah koneksi menggunakan HTTP/1.1 atau HTTP/2.

Jika titik akhir HTTP/2 dikonfigurasi tanpa TLS, ListenOptions.Protocols titik akhir harus diatur ke HttpProtocols.Http2. Titik akhir dengan beberapa protokol, seperti HttpProtocols.Http1AndHttp2 misalnya, tidak dapat digunakan tanpa TLS karena tidak ada negosiasi. Semua koneksi ke titik akhir yang tidak aman default ke HTTP/1.1, dan panggilan gRPC gagal.

Untuk informasi selengkapnya tentang mengaktifkan HTTP/2 dan TLS dengan Kestrel, lihat Kestrel konfigurasi titik akhir.

Catatan

macOS tidak mendukung ASP.NET Core gRPC dengan TLS sebelum .NET 8. Konfigurasi tambahan diperlukan untuk berhasil menjalankan layanan gRPC di macOS saat menggunakan .NET 7 atau yang lebih lama. Untuk informasi selengkapnya, lihat Tidak dapat memulai aplikasi gRPC ASP.NET Core di macOS.

IIS

Layanan Informasi Internet (IIS) adalah Server Web yang fleksibel, aman, dan dapat dikelola untuk menghosting aplikasi web, termasuk ASP.NET Core. .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru diperlukan untuk menghosting layanan gRPC dengan IIS.

IIS harus dikonfigurasi untuk menggunakan TLS dan HTTP/2. Untuk informasi selengkapnya, lihat Menggunakan ASP.NET Core dengan HTTP/2 di IIS.

HTTP.sys

HTTP.sys adalah server web untuk ASP.NET Core yang hanya berjalan di Windows. .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru diperlukan untuk menghosting layanan gRPC dengan HTTP.sys.

HTTP.sys harus dikonfigurasi untuk menggunakan TLS dan HTTP/2. Untuk informasi selengkapnya, lihat dukungan HTTP/2 server web HTTP.sys.

Host gRPC dalam proyek non-ASP.NET Core

Server ASP.NET Core gRPC biasanya dibuat dari templat gRPC. File proyek yang dibuat oleh templat menggunakan Microsoft.NET.SDK.Web sebagai 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>

Nilai Microsoft.NET.SDK.Web SDK secara otomatis menambahkan referensi ke kerangka kerja ASP.NET Core. Referensi memungkinkan aplikasi untuk menggunakan jenis ASP.NET Core yang diperlukan untuk menghosting server.

Anda dapat menambahkan server gRPC ke proyek non-ASP.NET Core dengan pengaturan file proyek berikut:

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

File proyek sebelumnya:

  • Tidak digunakan Microsoft.NET.SDK.Web sebagai SDK.
  • Menambahkan referensi kerangka kerja ke Microsoft.AspNetCore.App.
    • Referensi kerangka kerja memungkinkan aplikasi non-ASP.NET Core, seperti Layanan Windows, aplikasi WPF, atau aplikasi WinForms untuk menggunakan API inti ASP.NET.
    • Aplikasi ini sekarang dapat menggunakan API ASP.NET Core untuk memulai server ASP.NET Core.
  • Menambahkan persyaratan gRPC:

Untuk informasi selengkapnya tentang menggunakan Microsoft.AspNetCore.App referensi kerangka kerja, lihat Menggunakan kerangka kerja bersama ASP.NET Core.

Integrasi dengan API inti ASP.NET

Layanan gRPC memiliki akses penuh ke fitur ASP.NET Core seperti Injeksi Dependensi (DI) dan Pengelogan. Misalnya, implementasi layanan dapat menyelesaikan layanan pencatat dari kontainer DI melalui konstruktor:

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

Secara default, implementasi layanan gRPC dapat menyelesaikan layanan DI lainnya dengan masa pakai apa pun (Singleton, Cakupan, atau Sementara).

Mengatasi HttpContext dalam metode gRPC

API gRPC menyediakan akses ke beberapa data pesan HTTP/2, seperti metode, host, header, dan trailer. Akses melalui argumen yang ServerCallContext diteruskan ke setiap metode 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 tidak menyediakan akses penuh ke HttpContext di semua API ASP.NET. Metode GetHttpContext ekstensi menyediakan akses penuh ke HttpContext yang mewakili pesan HTTP/2 yang mendasar di 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
        });
    }
}

Sumber Daya Tambahan:

Dokumen ini menunjukkan cara memulai layanan gRPC menggunakan ASP.NET Core.

Prasyarat

Mulai menggunakan layanan gRPC di ASP.NET Core

Lihat atau unduh sampel kode (cara mengunduh).

Lihat Mulai menggunakan layanan gRPC untuk instruksi terperinci tentang cara membuat proyek gRPC.

Menambahkan layanan gRPC ke aplikasi ASP.NET Core

gRPC memerlukan paket Grpc.AspNetCore.

Mengonfigurasi gRPC

Di Program.cs:

  • gRPC diaktifkan dengan AddGrpc metode .
  • Setiap layanan gRPC ditambahkan ke alur perutean melalui MapGrpcService metode .
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();

Jika Anda ingin melihat komentar kode yang diterjemahkan ke bahasa selain bahasa Inggris, beri tahu kami dalam masalah diskusi GitHub ini.

ASP.NET Middleware core dan fitur berbagi alur perutean, oleh karena itu aplikasi dapat dikonfigurasi untuk melayani penangan permintaan tambahan. Penangan permintaan tambahan, seperti pengontrol MVC, bekerja secara paralel dengan layanan gRPC yang dikonfigurasi.

Opsi server

Layanan gRPC dapat dihosting oleh semua server ASP.NET Core bawaan.

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

†Requires .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru.

Untuk informasi selengkapnya tentang memilih server yang tepat untuk aplikasi ASP.NET Core, lihat Implementasi server web di ASP.NET Core.

Kestrel

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel berfokus pada performa tinggi dan pemanfaatan memori, tetapi tidak memiliki beberapa fitur canggih dalam HTTP.sys seperti berbagi port.

Kestrel Titik akhir gRPC:

HTTP/2

gRPC memerlukan HTTP/2. gRPC untuk ASP.NET Core memvalidasi HttpRequest.Protocol adalah HTTP/2.

Kestrelmendukung HTTP/2 pada sebagian besar sistem operasi modern. Kestrel titik akhir dikonfigurasi untuk mendukung koneksi HTTP/1.1 dan HTTP/2 secara default.

TLS

Kestrel titik akhir yang digunakan untuk gRPC harus diamankan dengan TLS. Dalam pengembangan, titik akhir yang diamankan dengan TLS secara otomatis dibuat https://localhost:5001 pada saat sertifikat pengembangan ASP.NET Core ada. Tidak diperlukan konfigurasi. Awalan https Kestrel memverifikasi titik akhir menggunakan TLS.

Dalam produksi, TLS harus dikonfigurasi secara eksplisit. Dalam contoh berikut appsettings.json , titik akhir HTTP/2 yang diamankan dengan TLS disediakan:

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

Atau, Kestrel titik akhir dapat dikonfigurasi di 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>");
    });
});

Untuk informasi selengkapnya tentang mengaktifkan TLS dengan Kestrel, lihat Kestrel Konfigurasi titik akhir HTTPS.

Negosiasi protokol

TLS digunakan untuk lebih dari mengamankan komunikasi. Jabat tangan TLS Application-Layer Protocol Negotiation (ALPN) digunakan untuk menegosiasikan protokol koneksi antara klien dan server ketika titik akhir mendukung beberapa protokol. Negosiasi ini menentukan apakah koneksi menggunakan HTTP/1.1 atau HTTP/2.

Jika titik akhir HTTP/2 dikonfigurasi tanpa TLS, ListenOptions.Protocols titik akhir harus diatur ke HttpProtocols.Http2. Titik akhir dengan beberapa protokol, seperti HttpProtocols.Http1AndHttp2 misalnya, tidak dapat digunakan tanpa TLS karena tidak ada negosiasi. Semua koneksi ke titik akhir yang tidak aman default ke HTTP/1.1, dan panggilan gRPC gagal.

Untuk informasi selengkapnya tentang mengaktifkan HTTP/2 dan TLS dengan Kestrel, lihat Kestrel konfigurasi titik akhir.

Catatan

macOS tidak mendukung ASP.NET Core gRPC dengan TLS sebelum .NET 8. Konfigurasi tambahan diperlukan untuk berhasil menjalankan layanan gRPC di macOS saat menggunakan .NET 7 atau yang lebih lama. Untuk informasi selengkapnya, lihat Tidak dapat memulai aplikasi gRPC ASP.NET Core di macOS.

IIS

Layanan Informasi Internet (IIS) adalah Server Web yang fleksibel, aman, dan dapat dikelola untuk menghosting aplikasi web, termasuk ASP.NET Core. .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru diperlukan untuk menghosting layanan gRPC dengan IIS.

IIS harus dikonfigurasi untuk menggunakan TLS dan HTTP/2. Untuk informasi selengkapnya, lihat Menggunakan ASP.NET Core dengan HTTP/2 di IIS.

HTTP.sys

HTTP.sys adalah server web untuk ASP.NET Core yang hanya berjalan di Windows. .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru diperlukan untuk menghosting layanan gRPC dengan HTTP.sys.

HTTP.sys harus dikonfigurasi untuk menggunakan TLS dan HTTP/2. Untuk informasi selengkapnya, lihat dukungan HTTP/2 server web HTTP.sys.

Host gRPC dalam proyek non-ASP.NET Core

Server ASP.NET Core gRPC biasanya dibuat dari templat gRPC. File proyek yang dibuat oleh templat menggunakan Microsoft.NET.SDK.Web sebagai 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>

Nilai Microsoft.NET.SDK.Web SDK secara otomatis menambahkan referensi ke kerangka kerja ASP.NET Core. Referensi memungkinkan aplikasi untuk menggunakan jenis ASP.NET Core yang diperlukan untuk menghosting server.

Anda dapat menambahkan server gRPC ke proyek non-ASP.NET Core dengan pengaturan file proyek berikut:

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

File proyek sebelumnya:

  • Tidak digunakan Microsoft.NET.SDK.Web sebagai SDK.
  • Menambahkan referensi kerangka kerja ke Microsoft.AspNetCore.App.
    • Referensi kerangka kerja memungkinkan aplikasi non-ASP.NET Core, seperti Layanan Windows, aplikasi WPF, atau aplikasi WinForms untuk menggunakan API inti ASP.NET.
    • Aplikasi ini sekarang dapat menggunakan API ASP.NET Core untuk memulai server ASP.NET Core.
  • Menambahkan persyaratan gRPC:

Untuk informasi selengkapnya tentang menggunakan Microsoft.AspNetCore.App referensi kerangka kerja, lihat Menggunakan kerangka kerja bersama ASP.NET Core.

Integrasi dengan API inti ASP.NET

Layanan gRPC memiliki akses penuh ke fitur ASP.NET Core seperti Injeksi Dependensi (DI) dan Pengelogan. Misalnya, implementasi layanan dapat menyelesaikan layanan pencatat dari kontainer DI melalui konstruktor:

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

Secara default, implementasi layanan gRPC dapat menyelesaikan layanan DI lainnya dengan masa pakai apa pun (Singleton, Cakupan, atau Sementara).

Mengatasi HttpContext dalam metode gRPC

API gRPC menyediakan akses ke beberapa data pesan HTTP/2, seperti metode, host, header, dan trailer. Akses melalui argumen yang ServerCallContext diteruskan ke setiap metode 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 tidak menyediakan akses penuh ke HttpContext di semua API ASP.NET. Metode GetHttpContext ekstensi menyediakan akses penuh ke HttpContext yang mewakili pesan HTTP/2 yang mendasar di 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
        });
    }
}

Sumber Daya Tambahan:

Dokumen ini menunjukkan cara memulai layanan gRPC menggunakan ASP.NET Core.

Prasyarat

Mulai menggunakan layanan gRPC di ASP.NET Core

Lihat atau unduh sampel kode (cara mengunduh).

Lihat Mulai menggunakan layanan gRPC untuk instruksi terperinci tentang cara membuat proyek gRPC.

Menambahkan layanan gRPC ke aplikasi ASP.NET Core

gRPC memerlukan paket Grpc.AspNetCore.

Mengonfigurasi gRPC

Di Program.cs:

  • gRPC diaktifkan dengan AddGrpc metode .
  • Setiap layanan gRPC ditambahkan ke alur perutean melalui MapGrpcService metode .
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();

Jika Anda ingin melihat komentar kode yang diterjemahkan ke bahasa selain bahasa Inggris, beri tahu kami dalam masalah diskusi GitHub ini.

ASP.NET Middleware core dan fitur berbagi alur perutean, oleh karena itu aplikasi dapat dikonfigurasi untuk melayani penangan permintaan tambahan. Penangan permintaan tambahan, seperti pengontrol MVC, bekerja secara paralel dengan layanan gRPC yang dikonfigurasi.

Opsi server

Layanan gRPC dapat dihosting oleh semua server ASP.NET Core bawaan.

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

†Requires .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru.

Untuk informasi selengkapnya tentang memilih server yang tepat untuk aplikasi ASP.NET Core, lihat Implementasi server web di ASP.NET Core.

Kestrel

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel berfokus pada performa tinggi dan pemanfaatan memori, tetapi tidak memiliki beberapa fitur canggih dalam HTTP.sys seperti berbagi port.

Kestrel Titik akhir gRPC:

HTTP/2

gRPC memerlukan HTTP/2. gRPC untuk ASP.NET Core memvalidasi HttpRequest.Protocol adalah HTTP/2.

Kestrelmendukung HTTP/2 pada sebagian besar sistem operasi modern. Kestrel titik akhir dikonfigurasi untuk mendukung koneksi HTTP/1.1 dan HTTP/2 secara default.

TLS

Kestrel titik akhir yang digunakan untuk gRPC harus diamankan dengan TLS. Dalam pengembangan, titik akhir yang diamankan dengan TLS secara otomatis dibuat https://localhost:5001 pada saat sertifikat pengembangan ASP.NET Core ada. Tidak diperlukan konfigurasi. Awalan https Kestrel memverifikasi titik akhir menggunakan TLS.

Dalam produksi, TLS harus dikonfigurasi secara eksplisit. Dalam contoh berikut appsettings.json , titik akhir HTTP/2 yang diamankan dengan TLS disediakan:

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

Atau, Kestrel titik akhir dapat dikonfigurasi di 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>");
    });
});

Untuk informasi selengkapnya tentang mengaktifkan TLS dengan Kestrel, lihat Kestrel Konfigurasi titik akhir HTTPS.

Negosiasi protokol

TLS digunakan untuk lebih dari mengamankan komunikasi. Jabat tangan TLS Application-Layer Protocol Negotiation (ALPN) digunakan untuk menegosiasikan protokol koneksi antara klien dan server ketika titik akhir mendukung beberapa protokol. Negosiasi ini menentukan apakah koneksi menggunakan HTTP/1.1 atau HTTP/2.

Jika titik akhir HTTP/2 dikonfigurasi tanpa TLS, ListenOptions.Protocols titik akhir harus diatur ke HttpProtocols.Http2. Titik akhir dengan beberapa protokol, seperti HttpProtocols.Http1AndHttp2 misalnya, tidak dapat digunakan tanpa TLS karena tidak ada negosiasi. Semua koneksi ke titik akhir yang tidak aman default ke HTTP/1.1, dan panggilan gRPC gagal.

Untuk informasi selengkapnya tentang mengaktifkan HTTP/2 dan TLS dengan Kestrel, lihat Kestrel konfigurasi titik akhir.

Catatan

macOS tidak mendukung ASP.NET Core gRPC dengan TLS sebelum .NET 8. Konfigurasi tambahan diperlukan untuk berhasil menjalankan layanan gRPC di macOS saat menggunakan .NET 7 atau yang lebih lama. Untuk informasi selengkapnya, lihat Tidak dapat memulai aplikasi gRPC ASP.NET Core di macOS.

IIS

Layanan Informasi Internet (IIS) adalah Server Web yang fleksibel, aman, dan dapat dikelola untuk menghosting aplikasi web, termasuk ASP.NET Core. .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru diperlukan untuk menghosting layanan gRPC dengan IIS.

IIS harus dikonfigurasi untuk menggunakan TLS dan HTTP/2. Untuk informasi selengkapnya, lihat Menggunakan ASP.NET Core dengan HTTP/2 di IIS.

HTTP.sys

HTTP.sys adalah server web untuk ASP.NET Core yang hanya berjalan di Windows. .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru diperlukan untuk menghosting layanan gRPC dengan HTTP.sys.

HTTP.sys harus dikonfigurasi untuk menggunakan TLS dan HTTP/2. Untuk informasi selengkapnya, lihat dukungan HTTP/2 server web HTTP.sys.

Host gRPC dalam proyek non-ASP.NET Core

Server ASP.NET Core gRPC biasanya dibuat dari templat gRPC. File proyek yang dibuat oleh templat menggunakan Microsoft.NET.SDK.Web sebagai 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>

Nilai Microsoft.NET.SDK.Web SDK secara otomatis menambahkan referensi ke kerangka kerja ASP.NET Core. Referensi memungkinkan aplikasi untuk menggunakan jenis ASP.NET Core yang diperlukan untuk menghosting server.

Anda dapat menambahkan server gRPC ke proyek non-ASP.NET Core dengan pengaturan file proyek berikut:

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

File proyek sebelumnya:

  • Tidak digunakan Microsoft.NET.SDK.Web sebagai SDK.
  • Menambahkan referensi kerangka kerja ke Microsoft.AspNetCore.App.
    • Referensi kerangka kerja memungkinkan aplikasi non-ASP.NET Core, seperti Layanan Windows, aplikasi WPF, atau aplikasi WinForms untuk menggunakan API inti ASP.NET.
    • Aplikasi ini sekarang dapat menggunakan API ASP.NET Core untuk memulai server ASP.NET Core.
  • Menambahkan persyaratan gRPC:

Untuk informasi selengkapnya tentang menggunakan Microsoft.AspNetCore.App referensi kerangka kerja, lihat Menggunakan kerangka kerja bersama ASP.NET Core.

Integrasi dengan API inti ASP.NET

Layanan gRPC memiliki akses penuh ke fitur ASP.NET Core seperti Injeksi Dependensi (DI) dan Pengelogan. Misalnya, implementasi layanan dapat menyelesaikan layanan pencatat dari kontainer DI melalui konstruktor:

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

Secara default, implementasi layanan gRPC dapat menyelesaikan layanan DI lainnya dengan masa pakai apa pun (Singleton, Cakupan, atau Sementara).

Mengatasi HttpContext dalam metode gRPC

API gRPC menyediakan akses ke beberapa data pesan HTTP/2, seperti metode, host, header, dan trailer. Akses melalui argumen yang ServerCallContext diteruskan ke setiap metode 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 tidak menyediakan akses penuh ke HttpContext di semua API ASP.NET. Metode GetHttpContext ekstensi menyediakan akses penuh ke HttpContext yang mewakili pesan HTTP/2 yang mendasar di 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
        });
    }
}

Sumber Daya Tambahan:

Dokumen ini menunjukkan cara memulai layanan gRPC menggunakan ASP.NET Core.

Prasyarat

Mulai menggunakan layanan gRPC di ASP.NET Core

Lihat atau unduh sampel kode (cara mengunduh).

Lihat Mulai menggunakan layanan gRPC untuk instruksi terperinci tentang cara membuat proyek gRPC.

Menambahkan layanan gRPC ke aplikasi ASP.NET Core

gRPC memerlukan paket Grpc.AspNetCore.

Mengonfigurasi gRPC

Di Startup.cs:

  • gRPC diaktifkan dengan AddGrpc metode .
  • Setiap layanan gRPC ditambahkan ke alur perutean melalui MapGrpcService metode .
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>();
        });
    }
}

Jika Anda ingin melihat komentar kode yang diterjemahkan ke bahasa selain bahasa Inggris, beri tahu kami dalam masalah diskusi GitHub ini.

ASP.NET Middleware core dan fitur berbagi alur perutean, oleh karena itu aplikasi dapat dikonfigurasi untuk melayani penangan permintaan tambahan. Penangan permintaan tambahan, seperti pengontrol MVC, bekerja secara paralel dengan layanan gRPC yang dikonfigurasi.

Opsi server

Layanan gRPC dapat dihosting oleh semua server ASP.NET Core bawaan.

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

†Requires .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru.

Untuk informasi selengkapnya tentang memilih server yang tepat untuk aplikasi ASP.NET Core, lihat Implementasi server web di ASP.NET Core.

Kestrel

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel berfokus pada performa tinggi dan pemanfaatan memori, tetapi tidak memiliki beberapa fitur canggih dalam HTTP.sys seperti berbagi port.

Kestrel Titik akhir gRPC:

HTTP/2

gRPC memerlukan HTTP/2. gRPC untuk ASP.NET Core memvalidasi HttpRequest.Protocol adalah HTTP/2.

Kestrelmendukung HTTP/2 pada sebagian besar sistem operasi modern. Kestrel titik akhir dikonfigurasi untuk mendukung koneksi HTTP/1.1 dan HTTP/2 secara default.

TLS

Kestrel titik akhir yang digunakan untuk gRPC harus diamankan dengan TLS. Dalam pengembangan, titik akhir yang diamankan dengan TLS secara otomatis dibuat https://localhost:5001 pada saat sertifikat pengembangan ASP.NET Core ada. Tidak diperlukan konfigurasi. Awalan https Kestrel memverifikasi titik akhir menggunakan TLS.

Dalam produksi, TLS harus dikonfigurasi secara eksplisit. Dalam contoh berikut appsettings.json , titik akhir HTTP/2 yang diamankan dengan TLS disediakan:

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

Atau, Kestrel titik akhir dapat dikonfigurasi di 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>();
        });

Untuk informasi selengkapnya tentang mengaktifkan TLS dengan Kestrel, lihat Kestrel Konfigurasi titik akhir HTTPS.

Negosiasi protokol

TLS digunakan untuk lebih dari mengamankan komunikasi. Jabat tangan TLS Application-Layer Protocol Negotiation (ALPN) digunakan untuk menegosiasikan protokol koneksi antara klien dan server ketika titik akhir mendukung beberapa protokol. Negosiasi ini menentukan apakah koneksi menggunakan HTTP/1.1 atau HTTP/2.

Jika titik akhir HTTP/2 dikonfigurasi tanpa TLS, ListenOptions.Protocols titik akhir harus diatur ke HttpProtocols.Http2. Titik akhir dengan beberapa protokol, seperti HttpProtocols.Http1AndHttp2 misalnya, tidak dapat digunakan tanpa TLS karena tidak ada negosiasi. Semua koneksi ke titik akhir yang tidak aman default ke HTTP/1.1, dan panggilan gRPC gagal.

Untuk informasi selengkapnya tentang mengaktifkan HTTP/2 dan TLS dengan Kestrel, lihat Kestrel konfigurasi titik akhir.

Catatan

macOS tidak mendukung ASP.NET Core gRPC dengan TLS sebelum .NET 8. Konfigurasi tambahan diperlukan untuk berhasil menjalankan layanan gRPC di macOS saat menggunakan .NET 7 atau yang lebih lama. Untuk informasi selengkapnya, lihat Tidak dapat memulai aplikasi gRPC ASP.NET Core di macOS.

IIS

Layanan Informasi Internet (IIS) adalah Server Web yang fleksibel, aman, dan dapat dikelola untuk menghosting aplikasi web, termasuk ASP.NET Core. .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru diperlukan untuk menghosting layanan gRPC dengan IIS.

IIS harus dikonfigurasi untuk menggunakan TLS dan HTTP/2. Untuk informasi selengkapnya, lihat Menggunakan ASP.NET Core dengan HTTP/2 di IIS.

HTTP.sys

HTTP.sys adalah server web untuk ASP.NET Core yang hanya berjalan di Windows. .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru diperlukan untuk menghosting layanan gRPC dengan HTTP.sys.

HTTP.sys harus dikonfigurasi untuk menggunakan TLS dan HTTP/2. Untuk informasi selengkapnya, lihat dukungan HTTP/2 server web HTTP.sys.

Host gRPC dalam proyek non-ASP.NET Core

Server ASP.NET Core gRPC biasanya dibuat dari templat gRPC. File proyek yang dibuat oleh templat menggunakan Microsoft.NET.SDK.Web sebagai 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>

Nilai Microsoft.NET.SDK.Web SDK secara otomatis menambahkan referensi ke kerangka kerja ASP.NET Core. Referensi memungkinkan aplikasi untuk menggunakan jenis ASP.NET Core yang diperlukan untuk menghosting server.

Anda dapat menambahkan server gRPC ke proyek non-ASP.NET Core dengan pengaturan file proyek berikut:

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

File proyek sebelumnya:

  • Tidak digunakan Microsoft.NET.SDK.Web sebagai SDK.
  • Menambahkan referensi kerangka kerja ke Microsoft.AspNetCore.App.
    • Referensi kerangka kerja memungkinkan aplikasi non-ASP.NET Core, seperti Layanan Windows, aplikasi WPF, atau aplikasi WinForms untuk menggunakan API inti ASP.NET.
    • Aplikasi ini sekarang dapat menggunakan API ASP.NET Core untuk memulai server ASP.NET Core.
  • Menambahkan persyaratan gRPC:

Untuk informasi selengkapnya tentang menggunakan Microsoft.AspNetCore.App referensi kerangka kerja, lihat Menggunakan kerangka kerja bersama ASP.NET Core.

Integrasi dengan API inti ASP.NET

Layanan gRPC memiliki akses penuh ke fitur ASP.NET Core seperti Injeksi Dependensi (DI) dan Pengelogan. Misalnya, implementasi layanan dapat menyelesaikan layanan pencatat dari kontainer DI melalui konstruktor:

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

Secara default, implementasi layanan gRPC dapat menyelesaikan layanan DI lainnya dengan masa pakai apa pun (Singleton, Cakupan, atau Sementara).

Mengatasi HttpContext dalam metode gRPC

API gRPC menyediakan akses ke beberapa data pesan HTTP/2, seperti metode, host, header, dan trailer. Akses melalui argumen yang ServerCallContext diteruskan ke setiap metode 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 tidak menyediakan akses penuh ke HttpContext di semua API ASP.NET. Metode GetHttpContext ekstensi menyediakan akses penuh ke HttpContext yang mewakili pesan HTTP/2 yang mendasar di 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
        });
    }
}

Sumber Daya Tambahan:

Dokumen ini menunjukkan cara memulai layanan gRPC menggunakan ASP.NET Core.

Prasyarat

Mulai menggunakan layanan gRPC di ASP.NET Core

Lihat atau unduh sampel kode (cara mengunduh).

Lihat Mulai menggunakan layanan gRPC untuk instruksi terperinci tentang cara membuat proyek gRPC.

Menambahkan layanan gRPC ke aplikasi ASP.NET Core

gRPC memerlukan paket Grpc.AspNetCore.

Mengonfigurasi gRPC

Di Startup.cs:

  • gRPC diaktifkan dengan AddGrpc metode .
  • Setiap layanan gRPC ditambahkan ke alur perutean melalui MapGrpcService metode .
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>();
        });
    }
}

Jika Anda ingin melihat komentar kode yang diterjemahkan ke bahasa selain bahasa Inggris, beri tahu kami dalam masalah diskusi GitHub ini.

ASP.NET Middleware core dan fitur berbagi alur perutean, oleh karena itu aplikasi dapat dikonfigurasi untuk melayani penangan permintaan tambahan. Penangan permintaan tambahan, seperti pengontrol MVC, bekerja secara paralel dengan layanan gRPC yang dikonfigurasi.

Opsi server

Layanan gRPC dapat dihosting oleh semua server ASP.NET Core bawaan.

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

†Requires .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru.

Untuk informasi selengkapnya tentang memilih server yang tepat untuk aplikasi ASP.NET Core, lihat Implementasi server web di ASP.NET Core.

Kestrel

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel berfokus pada performa tinggi dan pemanfaatan memori, tetapi tidak memiliki beberapa fitur canggih dalam HTTP.sys seperti berbagi port.

Kestrel Titik akhir gRPC:

HTTP/2

gRPC memerlukan HTTP/2. gRPC untuk ASP.NET Core memvalidasi HttpRequest.Protocol adalah HTTP/2.

Kestrelmendukung HTTP/2 pada sebagian besar sistem operasi modern. Kestrel titik akhir dikonfigurasi untuk mendukung koneksi HTTP/1.1 dan HTTP/2 secara default.

TLS

Kestrel titik akhir yang digunakan untuk gRPC harus diamankan dengan TLS. Dalam pengembangan, titik akhir yang diamankan dengan TLS secara otomatis dibuat https://localhost:5001 pada saat sertifikat pengembangan ASP.NET Core ada. Tidak diperlukan konfigurasi. Awalan https Kestrel memverifikasi titik akhir menggunakan TLS.

Dalam produksi, TLS harus dikonfigurasi secara eksplisit. Dalam contoh berikut appsettings.json , titik akhir HTTP/2 yang diamankan dengan TLS disediakan:

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

Atau, Kestrel titik akhir dapat dikonfigurasi di 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>();
        });

Untuk informasi selengkapnya tentang mengaktifkan TLS dengan Kestrel, lihat Kestrel Konfigurasi titik akhir HTTPS.

Negosiasi protokol

TLS digunakan untuk lebih dari mengamankan komunikasi. Jabat tangan TLS Application-Layer Protocol Negotiation (ALPN) digunakan untuk menegosiasikan protokol koneksi antara klien dan server ketika titik akhir mendukung beberapa protokol. Negosiasi ini menentukan apakah koneksi menggunakan HTTP/1.1 atau HTTP/2.

Jika titik akhir HTTP/2 dikonfigurasi tanpa TLS, ListenOptions.Protocols titik akhir harus diatur ke HttpProtocols.Http2. Titik akhir dengan beberapa protokol, seperti HttpProtocols.Http1AndHttp2 misalnya, tidak dapat digunakan tanpa TLS karena tidak ada negosiasi. Semua koneksi ke titik akhir yang tidak aman default ke HTTP/1.1, dan panggilan gRPC gagal.

Untuk informasi selengkapnya tentang mengaktifkan HTTP/2 dan TLS dengan Kestrel, lihat Kestrel konfigurasi titik akhir.

Catatan

macOS tidak mendukung ASP.NET Core gRPC dengan TLS sebelum .NET 8. Konfigurasi tambahan diperlukan untuk berhasil menjalankan layanan gRPC di macOS saat menggunakan .NET 7 atau yang lebih lama. Untuk informasi selengkapnya, lihat Tidak dapat memulai aplikasi gRPC ASP.NET Core di macOS.

Host gRPC dalam proyek non-ASP.NET Core

Server ASP.NET Core gRPC biasanya dibuat dari templat gRPC. File proyek yang dibuat oleh templat menggunakan Microsoft.NET.SDK.Web sebagai 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>

Nilai Microsoft.NET.SDK.Web SDK secara otomatis menambahkan referensi ke kerangka kerja ASP.NET Core. Referensi memungkinkan aplikasi untuk menggunakan jenis ASP.NET Core yang diperlukan untuk menghosting server.

Anda dapat menambahkan server gRPC ke proyek non-ASP.NET Core dengan pengaturan file proyek berikut:

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

File proyek sebelumnya:

  • Tidak digunakan Microsoft.NET.SDK.Web sebagai SDK.
  • Menambahkan referensi kerangka kerja ke Microsoft.AspNetCore.App.
    • Referensi kerangka kerja memungkinkan aplikasi non-ASP.NET Core, seperti Layanan Windows, aplikasi WPF, atau aplikasi WinForms untuk menggunakan API inti ASP.NET.
    • Aplikasi ini sekarang dapat menggunakan API ASP.NET Core untuk memulai server ASP.NET Core.
  • Menambahkan persyaratan gRPC:

Untuk informasi selengkapnya tentang menggunakan Microsoft.AspNetCore.App referensi kerangka kerja, lihat Menggunakan kerangka kerja bersama ASP.NET Core.

Integrasi dengan API inti ASP.NET

Layanan gRPC memiliki akses penuh ke fitur ASP.NET Core seperti Injeksi Dependensi (DI) dan Pengelogan. Misalnya, implementasi layanan dapat menyelesaikan layanan pencatat dari kontainer DI melalui konstruktor:

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

Secara default, implementasi layanan gRPC dapat menyelesaikan layanan DI lainnya dengan masa pakai apa pun (Singleton, Cakupan, atau Sementara).

Mengatasi HttpContext dalam metode gRPC

API gRPC menyediakan akses ke beberapa data pesan HTTP/2, seperti metode, host, header, dan trailer. Akses melalui argumen yang ServerCallContext diteruskan ke setiap metode 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 tidak menyediakan akses penuh ke HttpContext di semua API ASP.NET. Metode GetHttpContext ekstensi menyediakan akses penuh ke HttpContext yang mewakili pesan HTTP/2 yang mendasar di 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
        });
    }
}

Sumber Daya Tambahan:

Dokumen ini menunjukkan cara memulai layanan gRPC menggunakan ASP.NET Core.

Prasyarat

Mulai menggunakan layanan gRPC di ASP.NET Core

Lihat atau unduh sampel kode (cara mengunduh).

Lihat Mulai menggunakan layanan gRPC untuk instruksi terperinci tentang cara membuat proyek gRPC.

Menambahkan layanan gRPC ke aplikasi ASP.NET Core

gRPC memerlukan paket Grpc.AspNetCore.

Mengonfigurasi gRPC

Di Startup.cs:

  • gRPC diaktifkan dengan AddGrpc metode .
  • Setiap layanan gRPC ditambahkan ke alur perutean melalui MapGrpcService metode .
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>();
        });
    }
}

Jika Anda ingin melihat komentar kode yang diterjemahkan ke bahasa selain bahasa Inggris, beri tahu kami dalam masalah diskusi GitHub ini.

ASP.NET Middleware core dan fitur berbagi alur perutean, oleh karena itu aplikasi dapat dikonfigurasi untuk melayani penangan permintaan tambahan. Penangan permintaan tambahan, seperti pengontrol MVC, bekerja secara paralel dengan layanan gRPC yang dikonfigurasi.

Opsi server

Layanan gRPC dapat dihosting oleh semua server ASP.NET Core bawaan.

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

†Requires .NET 5 dan Windows 11 Build 22000 atau Windows Server 2022 Build 20348 atau yang lebih baru.

Untuk informasi selengkapnya tentang memilih server yang tepat untuk aplikasi ASP.NET Core, lihat Implementasi server web di ASP.NET Core.

Kestrel

Kestrel adalah server web lintas platform untuk ASP.NET Core. Kestrel berfokus pada performa tinggi dan pemanfaatan memori, tetapi tidak memiliki beberapa fitur canggih dalam HTTP.sys seperti berbagi port.

Kestrel Titik akhir gRPC:

HTTP/2

gRPC memerlukan HTTP/2. gRPC untuk ASP.NET Core memvalidasi HttpRequest.Protocol adalah HTTP/2.

Kestrelmendukung HTTP/2 pada sebagian besar sistem operasi modern. Kestrel titik akhir dikonfigurasi untuk mendukung koneksi HTTP/1.1 dan HTTP/2 secara default.

TLS

Kestrel titik akhir yang digunakan untuk gRPC harus diamankan dengan TLS. Dalam pengembangan, titik akhir yang diamankan dengan TLS secara otomatis dibuat https://localhost:5001 pada saat sertifikat pengembangan ASP.NET Core ada. Tidak diperlukan konfigurasi. Awalan https Kestrel memverifikasi titik akhir menggunakan TLS.

Dalam produksi, TLS harus dikonfigurasi secara eksplisit. Dalam contoh berikut appsettings.json , titik akhir HTTP/2 yang diamankan dengan TLS disediakan:

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

Atau, Kestrel titik akhir dapat dikonfigurasi di 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>();
        });

Untuk informasi selengkapnya tentang mengaktifkan TLS dengan Kestrel, lihat Kestrel Konfigurasi titik akhir HTTPS.

Negosiasi protokol

TLS digunakan untuk lebih dari mengamankan komunikasi. Jabat tangan TLS Application-Layer Protocol Negotiation (ALPN) digunakan untuk menegosiasikan protokol koneksi antara klien dan server ketika titik akhir mendukung beberapa protokol. Negosiasi ini menentukan apakah koneksi menggunakan HTTP/1.1 atau HTTP/2.

Jika titik akhir HTTP/2 dikonfigurasi tanpa TLS, ListenOptions.Protocols titik akhir harus diatur ke HttpProtocols.Http2. Titik akhir dengan beberapa protokol, seperti HttpProtocols.Http1AndHttp2 misalnya, tidak dapat digunakan tanpa TLS karena tidak ada negosiasi. Semua koneksi ke titik akhir yang tidak aman default ke HTTP/1.1, dan panggilan gRPC gagal.

Untuk informasi selengkapnya tentang mengaktifkan HTTP/2 dan TLS dengan Kestrel, lihat Kestrel konfigurasi titik akhir.

Catatan

macOS tidak mendukung ASP.NET Core gRPC dengan TLS sebelum .NET 8. Konfigurasi tambahan diperlukan untuk berhasil menjalankan layanan gRPC di macOS saat menggunakan .NET 7 atau yang lebih lama. Untuk informasi selengkapnya, lihat Tidak dapat memulai aplikasi gRPC ASP.NET Core di macOS.

Host gRPC dalam proyek non-ASP.NET Core

Server ASP.NET Core gRPC biasanya dibuat dari templat gRPC. File proyek yang dibuat oleh templat menggunakan Microsoft.NET.SDK.Web sebagai 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>

Nilai Microsoft.NET.SDK.Web SDK secara otomatis menambahkan referensi ke kerangka kerja ASP.NET Core. Referensi memungkinkan aplikasi untuk menggunakan jenis ASP.NET Core yang diperlukan untuk menghosting server.

Anda dapat menambahkan server gRPC ke proyek non-ASP.NET Core dengan pengaturan file proyek berikut:

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

File proyek sebelumnya:

  • Tidak digunakan Microsoft.NET.SDK.Web sebagai SDK.
  • Menambahkan referensi kerangka kerja ke Microsoft.AspNetCore.App.
    • Referensi kerangka kerja memungkinkan aplikasi non-ASP.NET Core, seperti Layanan Windows, aplikasi WPF, atau aplikasi WinForms untuk menggunakan API inti ASP.NET.
    • Aplikasi ini sekarang dapat menggunakan API ASP.NET Core untuk memulai server ASP.NET Core.
  • Menambahkan persyaratan gRPC:

Untuk informasi selengkapnya tentang menggunakan Microsoft.AspNetCore.App referensi kerangka kerja, lihat Menggunakan kerangka kerja bersama ASP.NET Core.

Integrasi dengan API inti ASP.NET

Layanan gRPC memiliki akses penuh ke fitur ASP.NET Core seperti Injeksi Dependensi (DI) dan Pengelogan. Misalnya, implementasi layanan dapat menyelesaikan layanan pencatat dari kontainer DI melalui konstruktor:

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

Secara default, implementasi layanan gRPC dapat menyelesaikan layanan DI lainnya dengan masa pakai apa pun (Singleton, Cakupan, atau Sementara).

Mengatasi HttpContext dalam metode gRPC

API gRPC menyediakan akses ke beberapa data pesan HTTP/2, seperti metode, host, header, dan trailer. Akses melalui argumen yang ServerCallContext diteruskan ke setiap metode 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 tidak menyediakan akses penuh ke HttpContext di semua API ASP.NET. Metode GetHttpContext ekstensi menyediakan akses penuh ke HttpContext yang mewakili pesan HTTP/2 yang mendasar di 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
        });
    }
}

Sumber Daya Tambahan: