Aracılığıyla paylaş

ASP.NET Core ile gRPC Hizmetleri

  • Makale

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Bu belgede, ASP.NET Core kullanarak gRPC hizmetlerini kullanmaya başlama gösterilmektedir.

Önkoşullar

ASP.NET Core’da gRPC hizmeti ile çalışmaya başlama

Örnek kodu görüntüleme veya indirme (indirme).

gRPC projesi oluşturma hakkında ayrıntılı yönergeler için bkz . gRPC hizmetlerini kullanmaya başlama.

ASP.NET Core uygulamasına gRPC hizmeti ekleme

gRPC, Grpc.AspNetCore paketini gerektirir.

gRPC'yi yapılandırma

Program.cs içinde:

  • gRPC, AddGrpc ile etkinleştirilir.
  • Her bir gRPC hizmeti, MapGrpcService yöntemi aracılığıyla yönlendirme işlem hattına eklenir.
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();

Kod açıklamalarının İngilizce dışındaki dillere çevirisini görmek isterseniz, bunu bu GitHub tartışma konusunda bize bildirin.

ASP.NET Core ara yazılımı ve özellikleri yönlendirme işlem hattını paylaşır, bu nedenle bir uygulama ek istek işleyicileri sunmak üzere yapılandırılabilir. MVC denetleyicileri gibi ek istek işleyicileri, yapılandırılan gRPC hizmetleriyle paralel olarak çalışır.

Sunucu seçenekleri

gRPC hizmetleri tüm yerleşik ASP.NET Core sunucuları tarafından barındırılabilir.

  • Kestrel
  • TestSunucusu
  • IIS†
  • HTTP.sys†

†.NET 5 ve Windows 11 Sürüm 22000 veya Windows Server 2022 Sürüm 20348 veya sonraki sürümlerini gerektirir.

ASP.NET Core uygulaması için doğru sunucuyu seçme hakkında daha fazla bilgi için bkz . ASP.NET Core'da Web sunucusu uygulamaları.

Kestrel

Kestrel ASP.NET Core için platformlar arası bir web sunucusudur. Kestrel yüksek performans ve bellek kullanımına odaklanır, ancak HTTP.sys bağlantı noktası paylaşımı gibi bazı gelişmiş özelliklere sahip değildir.

Kestrel gRPC uç noktaları:

  • HTTP/2 gerektir.
  • Aktarım Katmanı Güvenliği (TLS) ile güvenliği sağlanmalıdır.

HTTP/2

gRPC http/2 gerektirir. ASP.NET Core için gRPC, HttpRequest.Protocol'unHTTP/2.

Kestrel çoğu modern işletim sisteminde HTTP/2'i destekler. Kestrel uç noktaları varsayılan olarak HTTP/1.1 ve HTTP/2 bağlantılarını destekleyecek şekilde yapılandırılır.

TLS

Kestrel gRPC için kullanılan uç noktaların güvenliği TLS ile sağlanmalıdır. Geliştirme aşamasında, ASP.NET Core geliştirme sertifikası mevcut olduğunda TLS ile güvenliği sağlanan bir uç nokta otomatik olarak oluşturulur https://localhost:5001 . Yapılandırma gerekmez. Ön https ek, uç noktanın Kestrel TLS kullandığını doğrular.

Üretimde TLS açıkça yapılandırılmalıdır. Aşağıdaki appsettings.json örnekte, TLS ile güvenliği sağlanan bir HTTP/2 uç noktası sağlanır:

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

Alternatif olarak, Kestrel uç noktalar Program.cs içinde yapılandırılabilir.

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

TLS'yi ile Kestreletkinleştirme hakkında daha fazla bilgi için bkz Kestrel . HTTPS uç noktası yapılandırması.

Protokol anlaşması

TLS, iletişimin güvenliğini sağlamaktan daha fazlası için kullanılır. TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışması, bir uç nokta birden çok protokolü desteklediğinde istemci ile sunucu arasında bağlantı protokolü anlaşması yapmak için kullanılır. Bu anlaşma, bağlantının HTTP/1.1 mi yoksa HTTP/2 mi kullandığını belirler.

BIR HTTP/2 uç noktası TLS olmadan yapılandırıldıysa, uç noktanın ListenOptions.Protocols değeri olarak HttpProtocols.Http2ayarlanmalıdır. Örneğin, HttpProtocols.Http1AndHttp2 birden çok protokole sahip bir uç nokta, anlaşma olmadığından TLS olmadan kullanılamaz. Güvenli olmayan uç noktaya yapılan tüm bağlantılar varsayılan olarak HTTP/1.1'dir ve gRPC çağrıları başarısız olur.

ile KestrelHTTP/2 ve TLS'yi etkinleştirme hakkında daha fazla bilgi için bkz Kestrel . uç nokta yapılandırması.

Not

macOS, .NET 8 öncesi TLS ile ASP.NET Core gRPC'leri desteklemez. .NET 7 veya önceki sürümleri kullanırken macOS üzerinde gRPC hizmetlerini başarıyla çalıştırmak için ek yapılandırma gereklidir. Daha fazla bilgi için bkz . macOS üzerinde ASP.NET Core gRPC uygulaması başlatılamıyor.

IIS

Internet Information Services (IIS), ASP.NET Core dahil olmak üzere web uygulamalarını barındırmak için esnek, güvenli ve yönetilebilir bir Web Sunucusudur. IIS ile gRPC hizmetlerini barındırmak için .NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya üzeri gerekir.

IIS, TLS ve HTTP/2 kullanacak şekilde yapılandırılmalıdır. Daha fazla bilgi için bkz: IIS'de HTTP/2 ile ASP.NET Core kullanma.

HTTP.sys

HTTP.sys, ASP.NET Core için yalnızca Windows üzerinde çalışan bir web sunucusudur. gRPC hizmetlerini HTTP.sys ile barındırmak için .NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya üzeri gerekir.

HTTP.sys TLS ve HTTP/2 kullanacak şekilde yapılandırılmalıdır. Daha fazla bilgi için bkz . HTTP.sys web sunucusu HTTP/2 desteği.

non-ASP.NET Core projelerinde gRPC barındırma

bir ASP.NET Core gRPC sunucusu genellikle gRPC şablonundan oluşturulur. Şablon tarafından oluşturulan proje dosyası SDK olarak kullanır Microsoft.NET.SDK.Web :

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

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

</Project>

Microsoft.NET.SDK.Web SDK değeri, ASP.NET Core çerçevesine otomatik olarak bir başvuru ekler. Başvuru, uygulamanın bir sunucuyu barındırmak için gereken ASP.NET Core türlerini kullanmasına olanak tanır.

Aşağıdaki proje dosyası ayarlarıyla non-ASP.NET Core projelerine bir gRPC sunucusu ekleyebilirsiniz:

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

Önceki proje dosyası:

  • Microsoft.NET.SDK.Web'yi SDK olarak kullanmaz.
  • Microsoft.AspNetCore.App öğesine bir çerçeve başvurusu ekler.
    • Çerçeve başvurusu, Windows Hizmetleri, WPF uygulamaları veya WinForms uygulamaları gibi non-ASP.NET Core uygulamalarının ASP.NET Core API'lerini kullanmasına olanak tanır.
    • Uygulama artık bir ASP.NET Core sunucusu başlatmak için ASP.NET Core API'lerini kullanabilir.
  • gRPC gereksinimlerini ekler:

Daha fazla bilgi için Microsoft.AspNetCore.App çerçeve referansını kullanma konusunda bkz. ASP.NET Core paylaşılan çerçevesini kullanma.

ASP.NET Core API'leriyle tümleştirme

gRPC hizmetleri, bağımlılık enjeksiyonu (DI) ve günlük tutmagibi ASP.NET Core özelliklerine tam erişime sahiptir. Örneğin, hizmet uygulaması DI kapsayıcısından bir günlükçü hizmetini çözümleyebilir.

Oluşturucu enjeksiyonu

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

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

Birincil oluşturucu ekleme (.NET 8 veya üzeri):

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

Varsayılan olarak, gRPC hizmeti uygulaması diğer DI hizmetlerini herhangi bir yaşam süresiyle (Tekil, Kapsamlı veya Geçici) çözümleyebilir.

gRPC yöntemlerinde HttpContext'i çözme

gRPC API'si yöntem, konak, üst bilgi ve fragmanlar gibi bazı HTTP/2 ileti verilerine erişim sağlar. Her gRPC yöntemine geçirilen bağımsız değişken ServerCallContext ile erişim sağlanır.

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

ServerCallContext tüm ASP.NET API'lerinde HttpContext için tam erişim sağlamaz. GetHttpContext uzantı yöntemi, ASP.NET API'lerinde temel alınan HTTP/2 iletisini temsil eden HttpContext'e tam erişim sağlar.

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

Ek kaynaklar

Bu belgede, ASP.NET Core kullanarak gRPC hizmetlerini kullanmaya başlama gösterilmektedir.

Önkoşullar

ASP.NET Core’da gRPC hizmeti ile çalışmaya başlama

Örnek kodu görüntüleme veya indirme (indirme).

gRPC projesi oluşturma hakkında ayrıntılı yönergeler için bkz . gRPC hizmetlerini kullanmaya başlama.

ASP.NET Core uygulamasına gRPC hizmeti ekleme

gRPC, Grpc.AspNetCore paketini gerektirir.

gRPC'yi yapılandırma

Program.cs içinde:

  • gRPC, AddGrpc yöntemiyle etkinleştirilir.
  • Her gRPC hizmeti, MapGrpcService yöntemi aracılığıyla yönlendirme işlem hattına eklenir.
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();

Kod açıklamalarının İngilizce dışındaki dillere çevirisini görmek isterseniz, bunu bu GitHub tartışma konusunda bize bildirin.

ASP.NET Core ara yazılımı ve özellikleri yönlendirme işlem hattını paylaşır, bu nedenle bir uygulama ek istek işleyicileri sunmak üzere yapılandırılabilir. MVC denetleyicileri gibi ek istek işleyicileri, yapılandırılan gRPC hizmetleriyle paralel olarak çalışır.

Sunucu seçenekleri

gRPC hizmetleri tüm yerleşik ASP.NET Core sunucuları tarafından barındırılabilir.

  • Kestrel
  • Test Sunucusu
  • IIS†
  • HTTP.sys†

†.NET 5 ve Windows 11 Sürüm 22000 veya Windows Server 2022 Sürüm 20348 veya sonrası gerektirir.

ASP.NET Core uygulaması için doğru sunucuyu seçme hakkında daha fazla bilgi için bkz . ASP.NET Core'da Web sunucusu uygulamaları.

Kestrel

Kestrel ASP.NET Core için platformlar arası bir web sunucusudur. Kestrel yüksek performans ve bellek kullanımına odaklanır, ancak HTTP.sys bağlantı noktası paylaşımı gibi bazı gelişmiş özelliklere sahip değildir.

Kestrel gRPC uç noktaları:

  • HTTP/2 gerektir.
  • Aktarım Katmanı Güvenliği (TLS) ile güvenliği sağlanmalıdır.

HTTP/2

gRPC http/2 gerektirir. ASP.NET Core için gRPC, HttpRequest.Protocol'unHTTP/2.

Kestrel çoğu modern işletim sisteminde HTTP/2'i destekler. Kestrel uç noktaları varsayılan olarak HTTP/1.1 ve HTTP/2 bağlantılarını destekleyecek şekilde yapılandırılır.

TLS

Kestrel gRPC için kullanılan uç noktaların güvenliği TLS ile sağlanmalıdır. Geliştirme aşamasında, ASP.NET Core geliştirme sertifikası mevcut olduğunda TLS ile güvenliği sağlanan bir uç nokta otomatik olarak oluşturulur https://localhost:5001 . Yapılandırma gerekmez. Ön https ek, uç noktanın Kestrel TLS kullandığını doğrular.

Üretimde TLS açıkça yapılandırılmalıdır. Aşağıdaki appsettings.json örnekte, TLS ile güvenliği sağlanan bir HTTP/2 uç noktası sağlanır:

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

Alternatif olarak, Program.cs içinde uç noktalar yapılandırılabilir:

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

TLS'yi ile Kestreletkinleştirme hakkında daha fazla bilgi için bkz Kestrel . HTTPS uç noktası yapılandırması.

Protokol anlaşması

TLS, iletişimin güvenliğini sağlamaktan daha fazlası için kullanılır. TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışması, bir uç nokta birden çok protokolü desteklediğinde istemci ile sunucu arasında bağlantı protokolü anlaşması yapmak için kullanılır. Bu anlaşma, bağlantının HTTP/1.1 mi yoksa HTTP/2 mi kullandığını belirler.

BIR HTTP/2 uç noktası TLS olmadan yapılandırıldıysa, uç noktanın ListenOptions.Protocols değeri olarak HttpProtocols.Http2ayarlanmalıdır. Örneğin, HttpProtocols.Http1AndHttp2 birden çok protokole sahip bir uç nokta, anlaşma olmadığından TLS olmadan kullanılamaz. Güvenli olmayan uç noktaya yapılan tüm bağlantılar varsayılan olarak HTTP/1.1'dir ve gRPC çağrıları başarısız olur.

ile KestrelHTTP/2 ve TLS'yi etkinleştirme hakkında daha fazla bilgi için bkz Kestrel . uç nokta yapılandırması.

Not

macOS, .NET 8 öncesi TLS ile ASP.NET Core gRPC'leri desteklemez. .NET 7 veya önceki sürümleri kullanırken macOS üzerinde gRPC hizmetlerini başarıyla çalıştırmak için ek yapılandırma gereklidir. Daha fazla bilgi için bkz . macOS üzerinde ASP.NET Core gRPC uygulaması başlatılamıyor.

IIS

Internet Information Services (IIS), ASP.NET Core dahil olmak üzere web uygulamalarını barındırmak için esnek, güvenli ve yönetilebilir bir Web Sunucusudur. IIS ile gRPC hizmetlerini barındırmak için .NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya üzeri gerekir.

IIS, TLS ve HTTP/2 kullanacak şekilde yapılandırılmalıdır. Daha fazla bilgi için bkz: IIS'de HTTP/2 ile ASP.NET Core kullanma.

HTTP.sys

HTTP.sys, ASP.NET Core için yalnızca Windows üzerinde çalışan bir web sunucusudur. gRPC hizmetlerini HTTP.sys ile barındırmak için .NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya üzeri gerekir.

HTTP.sys TLS ve HTTP/2 kullanacak şekilde yapılandırılmalıdır. Daha fazla bilgi için bkz . HTTP.sys web sunucusu HTTP/2 desteği.

non-ASP.NET Core projelerinde gRPC barındırma

bir ASP.NET Core gRPC sunucusu genellikle gRPC şablonundan oluşturulur. Şablon tarafından oluşturulan proje dosyası SDK olarak kullanır Microsoft.NET.SDK.Web :

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

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

</Project>

Microsoft.NET.SDK.Web SDK değeri, ASP.NET Core çerçevesine otomatik olarak bir başvuru ekler. Başvuru, uygulamanın bir sunucuyu barındırmak için gereken ASP.NET Core türlerini kullanmasına olanak tanır.

Aşağıdaki proje dosyası ayarlarıyla non-ASP.NET Core projelerine bir gRPC sunucusu ekleyebilirsiniz:

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

Önceki proje dosyası:

  • Microsoft.NET.SDK.Web'yi SDK olarak kullanmaz.
  • Bir çerçeve başvurusu Microsoft.AspNetCore.App öğesine ekler.
    • Çerçeve başvurusu, Windows Hizmetleri, WPF uygulamaları veya WinForms uygulamaları gibi non-ASP.NET Core uygulamalarının ASP.NET Core API'lerini kullanmasına olanak tanır.
    • Uygulama artık bir ASP.NET Core sunucusu başlatmak için ASP.NET Core API'lerini kullanabilir.
  • gRPC gereksinimlerini ekler:

Çerçeve başvurusunu Microsoft.AspNetCore.App kullanma hakkında daha fazla bilgi için ASP.NET Core paylaşılan çerçevesini kullanma konusuna bakın.

ASP.NET Core API'leriyle tümleştirme

gRPC hizmetleri, Bağımlılık Enjeksiyonu (DI) ve Günlük Kaydı gibi ASP.NET Core özelliklerine tam erişimi vardır. Örneğin, hizmet uygulaması oluşturucu aracılığıyla DI kapsayıcısından bir günlükçü hizmetini çözümleyebilir:

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

Varsayılan olarak, gRPC hizmeti uygulaması diğer DI hizmetlerini herhangi bir yaşam süresiyle (Tekil, Kapsamlı veya Geçici) çözümleyebilir.

gRPC yöntemlerinde HttpContext'i çözme

gRPC API'si yöntem, konak, üst bilgi ve fragmanlar gibi bazı HTTP/2 ileti verilerine erişim sağlar. Erişim, her gRPC yöntemine geçirilen ServerCallContext bağımsız değişkeni aracılığıyla sağlanır.

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

ServerCallContext tüm ASP.NET API'lerinde HttpContext 'e tam erişim sağlamaz. GetHttpContext uzantı yöntemi, ASP.NET API'lerinde temel alınan HTTP/2 iletisini temsil eden HttpContext aracılığıyla tam erişim sağlar.

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

Ek kaynaklar

Bu belgede, ASP.NET Core kullanarak gRPC hizmetlerini kullanmaya başlama gösterilmektedir.

Önkoşullar

ASP.NET Core’da gRPC hizmeti ile çalışmaya başlama

Örnek kodu görüntüleme veya indirme (indirme).

gRPC projesi oluşturma hakkında ayrıntılı yönergeler için bkz . gRPC hizmetlerini kullanmaya başlama.

ASP.NET Core uygulamasına gRPC hizmeti ekleme

gRPC, Grpc.AspNetCore paketini gerektirir.

gRPC'yi yapılandırma

Program.cs içinde:

  • gRPC, AddGrpc ile etkinleştirilir.
  • Her bir gRPC hizmeti MapGrpcService yöntemi aracılığıyla yönlendirme işlem hattına eklenir.
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();

Kod açıklamalarının İngilizce dışındaki dillere çevirisini görmek isterseniz, bunu bu GitHub tartışma konusunda bize bildirin.

ASP.NET Core ara yazılımı ve özellikleri yönlendirme işlem hattını paylaşır, bu nedenle bir uygulama ek istek işleyicileri sunmak üzere yapılandırılabilir. MVC denetleyicileri gibi ek istek işleyicileri, yapılandırılan gRPC hizmetleriyle paralel olarak çalışır.

Sunucu seçenekleri

gRPC hizmetleri tüm yerleşik ASP.NET Core sunucuları tarafından barındırılabilir.

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

.NET 5 ve Windows 11 Sürüm 22000 veya Windows Server 2022 Sürüm 20348 veya sonraki sürümlerini gerektirir.

ASP.NET Core uygulaması için doğru sunucuyu seçme hakkında daha fazla bilgi için bkz . ASP.NET Core'da Web sunucusu uygulamaları.

Kestrel

Kestrel ASP.NET Core için platformlar arası bir web sunucusudur. Kestrel yüksek performans ve bellek kullanımına odaklanır, ancak HTTP.sys bağlantı noktası paylaşımı gibi bazı gelişmiş özelliklere sahip değildir.

Kestrel gRPC uç noktaları:

  • HTTP/2 gerektir.
  • Aktarım Katmanı Güvenliği (TLS) ile güvenliği sağlanmalıdır.

HTTP/2

gRPC http/2 gerektirir. ASP.NET Core için gRPC, HttpRequest.Protocol'unHTTP/2.

Kestrel çoğu modern işletim sisteminde HTTP/2'i destekler. Kestrel uç noktaları varsayılan olarak HTTP/1.1 ve HTTP/2 bağlantılarını destekleyecek şekilde yapılandırılır.

TLS

Kestrel gRPC için kullanılan uç noktaların güvenliği TLS ile sağlanmalıdır. Geliştirme aşamasında, ASP.NET Core geliştirme sertifikası mevcut olduğunda TLS ile güvenliği sağlanan bir uç nokta otomatik olarak oluşturulur https://localhost:5001 . Yapılandırma gerekmez. Ön https ek, uç noktanın Kestrel TLS kullandığını doğrular.

Üretimde TLS açıkça yapılandırılmalıdır. Aşağıdaki appsettings.json örnekte, TLS ile güvenliği sağlanan bir HTTP/2 uç noktası sağlanır:

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

Alternatif olarak, Kestrel uç noktaları Program.cs içinde yapılandırılabilir.

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

TLS'yi ile Kestreletkinleştirme hakkında daha fazla bilgi için bkz Kestrel . HTTPS uç noktası yapılandırması.

Protokol anlaşması

TLS, iletişimin güvenliğini sağlamaktan daha fazlası için kullanılır. TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışması, bir uç nokta birden çok protokolü desteklediğinde istemci ile sunucu arasında bağlantı protokolü anlaşması yapmak için kullanılır. Bu anlaşma, bağlantının HTTP/1.1 mi yoksa HTTP/2 mi kullandığını belirler.

BIR HTTP/2 uç noktası TLS olmadan yapılandırıldıysa, uç noktanın ListenOptions.Protocols değeri olarak HttpProtocols.Http2ayarlanmalıdır. Örneğin, HttpProtocols.Http1AndHttp2 birden çok protokole sahip bir uç nokta, anlaşma olmadığından TLS olmadan kullanılamaz. Güvenli olmayan uç noktaya yapılan tüm bağlantılar varsayılan olarak HTTP/1.1'dir ve gRPC çağrıları başarısız olur.

ile KestrelHTTP/2 ve TLS'yi etkinleştirme hakkında daha fazla bilgi için bkz Kestrel . uç nokta yapılandırması.

Uyarı

macOS, .NET 8 öncesi TLS ile ASP.NET Core gRPC'leri desteklemez. .NET 7 veya önceki sürümleri kullanırken macOS üzerinde gRPC hizmetlerini başarıyla çalıştırmak için ek yapılandırma gereklidir. Daha fazla bilgi için bkz . macOS üzerinde ASP.NET Core gRPC uygulaması başlatılamıyor.

IIS

Internet Information Services (IIS), ASP.NET Core dahil olmak üzere web uygulamalarını barındırmak için esnek, güvenli ve yönetilebilir bir Web Sunucusudur. IIS ile gRPC hizmetlerini barındırmak için .NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya üzeri gerekir.

IIS, TLS ve HTTP/2 kullanacak şekilde yapılandırılmalıdır. Daha fazla bilgi için bkz HTTP/2 ile ASP.NET Core'u IIS'de Kullanma.

HTTP.sys

HTTP.sys, ASP.NET Core için yalnızca Windows üzerinde çalışan bir web sunucusudur. gRPC hizmetlerini HTTP.sys ile barındırmak için .NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya üzeri gerekir.

HTTP.sys TLS ve HTTP/2 kullanacak şekilde yapılandırılmalıdır. Daha fazla bilgi için bkz . HTTP.sys web sunucusu HTTP/2 desteği.

non-ASP.NET Core projelerinde gRPC barındırma

bir ASP.NET Core gRPC sunucusu genellikle gRPC şablonundan oluşturulur. Şablon tarafından oluşturulan proje dosyası SDK olarak kullanır Microsoft.NET.SDK.Web :

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

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

</Project>

Microsoft.NET.SDK.Web SDK değeri, ASP.NET Core çerçevesine otomatik olarak bir başvuru ekler. Başvuru, uygulamanın bir sunucuyu barındırmak için gereken ASP.NET Core türlerini kullanmasına olanak tanır.

Aşağıdaki proje dosyası ayarlarıyla non-ASP.NET Core projelerine bir gRPC sunucusu ekleyebilirsiniz:

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

Önceki proje dosyası:

  • Microsoft.NET.SDK.Web, SDK olarak kullanmaz.
  • Microsoft.AspNetCore.App öğesine bir çerçeve başvurusu ekler.
    • Çerçeve başvurusu, Windows Hizmetleri, WPF uygulamaları veya WinForms uygulamaları gibi non-ASP.NET Core uygulamalarının ASP.NET Core API'lerini kullanmasına olanak tanır.
    • Uygulama artık bir ASP.NET Core sunucusu başlatmak için ASP.NET Core API'lerini kullanabilir.
  • gRPC gereksinimlerini ekler:

Microsoft.AspNetCore.App çerçeve başvurusu hakkında daha fazla bilgi için, ASP.NET Core paylaşılan çerçevesini kullanma kısmına bakın.

ASP.NET Core API'leriyle tümleştirme

gRPC hizmetleri, Bağımlılık Enjeksiyonu (DI) ve Günlükleme (Logging) gibi ASP.NET Core özelliklerine tam erişime sahiptir. Örneğin, hizmet uygulaması, oluşturucu yoluyla DI kapsayıcısından bir log hizmetini çözümleyebilir.

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

Varsayılan olarak, gRPC hizmeti uygulaması diğer DI hizmetlerini herhangi bir yaşam süresiyle (Tekil, Kapsamlı veya Geçici) çözümleyebilir.

gRPC yöntemlerinde HttpContext'i çözme

gRPC API'si yöntem, konak, üst bilgi ve fragmanlar gibi bazı HTTP/2 ileti verilerine erişim sağlar. Access, her gRPC yöntemine geçirilen ServerCallContext bağımsız değişkeni ile sağlanır.

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

ServerCallContext, tüm ASP.NET API'lerinde HttpContext için tam erişim sağlamaz. GetHttpContext uzantı yöntemi, HttpContext temel alınan HTTP/2 iletisini temsil eden ASP.NET API'lerinde tam erişim sağlar.

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

Ek kaynaklar

Bu belgede, ASP.NET Core kullanarak gRPC hizmetlerini kullanmaya başlama gösterilmektedir.

Önkoşullar

ASP.NET Core’da gRPC hizmeti ile çalışmaya başlama

Örnek kodu görüntüleme veya indirme (indirme).

gRPC projesi oluşturma hakkında ayrıntılı yönergeler için bkz . gRPC hizmetlerini kullanmaya başlama.

ASP.NET Core uygulamasına gRPC hizmeti ekleme

gRPC, Grpc.AspNetCore paketini gerektirir.

gRPC'yi yapılandırma

Startup.cs içinde:

  • gRPC, AddGrpc yöntemiyle etkinleştirilir.
  • Her bir gRPC hizmeti MapGrpcService yöntemi ile yönlendirme işlem hattına eklenir.
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>();
        });
    }
}

Kod açıklamalarının İngilizce dışındaki dillere çevirisini görmek isterseniz, bunu bu GitHub tartışma konusunda bize bildirin.

ASP.NET Core ara yazılımı ve özellikleri yönlendirme işlem hattını paylaşır, bu nedenle bir uygulama ek istek işleyicileri sunmak üzere yapılandırılabilir. MVC denetleyicileri gibi ek istek işleyicileri, yapılandırılan gRPC hizmetleriyle paralel olarak çalışır.

Sunucu seçenekleri

gRPC hizmetleri tüm yerleşik ASP.NET Core sunucuları tarafından barındırılabilir.

  • Kestrel
  • TestSunucu
  • IIS†
  • HTTP.sys†

†.NET 5 ve Windows 11 Sürüm 22000 veya Windows Server 2022 Sürüm 20348 ya da sonraki sürümlerini gerektirir.

ASP.NET Core uygulaması için doğru sunucuyu seçme hakkında daha fazla bilgi için bkz . ASP.NET Core'da Web sunucusu uygulamaları.

Kestrel

Kestrel ASP.NET Core için platformlar arası bir web sunucusudur. Kestrel yüksek performans ve bellek kullanımına odaklanır, ancak HTTP.sys bağlantı noktası paylaşımı gibi bazı gelişmiş özelliklere sahip değildir.

Kestrel gRPC uç noktaları:

  • HTTP/2 gerektir.
  • Aktarım Katmanı Güvenliği (TLS) ile güvenliği sağlanmalıdır.

HTTP/2

gRPC http/2 gerektirir. ASP.NET Core için gRPC, HttpRequest.Protocol'unHTTP/2.

Kestrel çoğu modern işletim sisteminde HTTP/2'i destekler. Kestrel uç noktaları varsayılan olarak HTTP/1.1 ve HTTP/2 bağlantılarını destekleyecek şekilde yapılandırılır.

TLS

Kestrel gRPC için kullanılan uç noktaların güvenliği TLS ile sağlanmalıdır. Geliştirme aşamasında, ASP.NET Core geliştirme sertifikası mevcut olduğunda TLS ile güvenliği sağlanan bir uç nokta otomatik olarak oluşturulur https://localhost:5001 . Yapılandırma gerekmez. Ön https ek, uç noktanın Kestrel TLS kullandığını doğrular.

Üretimde TLS açıkça yapılandırılmalıdır. Aşağıdaki appsettings.json örnekte, TLS ile güvenliği sağlanan bir HTTP/2 uç noktası sağlanır:

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

Alternatif olarak, Kestrel uç noktalar Program.cs içinde yapılandırılabilir.

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

TLS'yi ile Kestreletkinleştirme hakkında daha fazla bilgi için bkz Kestrel . HTTPS uç noktası yapılandırması.

Protokol anlaşması

TLS, iletişimin güvenliğini sağlamaktan daha fazlası için kullanılır. TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışması, bir uç nokta birden çok protokolü desteklediğinde istemci ile sunucu arasında bağlantı protokolü anlaşması yapmak için kullanılır. Bu anlaşma, bağlantının HTTP/1.1 mi yoksa HTTP/2 mi kullandığını belirler.

BIR HTTP/2 uç noktası TLS olmadan yapılandırıldıysa, uç noktanın ListenOptions.Protocols değeri olarak HttpProtocols.Http2ayarlanmalıdır. Örneğin, HttpProtocols.Http1AndHttp2 birden çok protokole sahip bir uç nokta, anlaşma olmadığından TLS olmadan kullanılamaz. Güvenli olmayan uç noktaya yapılan tüm bağlantılar varsayılan olarak HTTP/1.1'dir ve gRPC çağrıları başarısız olur.

ile KestrelHTTP/2 ve TLS'yi etkinleştirme hakkında daha fazla bilgi için bkz Kestrel . uç nokta yapılandırması.

Not

macOS, .NET 8 öncesi TLS ile ASP.NET Core gRPC'leri desteklemez. .NET 7 veya önceki sürümleri kullanırken macOS üzerinde gRPC hizmetlerini başarıyla çalıştırmak için ek yapılandırma gereklidir. Daha fazla bilgi için bkz . macOS üzerinde ASP.NET Core gRPC uygulaması başlatılamıyor.

IIS

Internet Information Services (IIS), ASP.NET Core dahil olmak üzere web uygulamalarını barındırmak için esnek, güvenli ve yönetilebilir bir Web Sunucusudur. IIS ile gRPC hizmetlerini barındırmak için .NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya üzeri gerekir.

IIS, TLS ve HTTP/2 kullanacak şekilde yapılandırılmalıdır. Daha fazla bilgi için bkz HTTP/2 ile ASP.NET Core'u IIS üzerinde kullanma.

HTTP.sys

HTTP.sys, ASP.NET Core için yalnızca Windows üzerinde çalışan bir web sunucusudur. gRPC hizmetlerini HTTP.sys ile barındırmak için .NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya üzeri gerekir.

HTTP.sys TLS ve HTTP/2 kullanacak şekilde yapılandırılmalıdır. Daha fazla bilgi için bkz . HTTP.sys web sunucusu HTTP/2 desteği.

non-ASP.NET Core projelerinde gRPC barındırma

bir ASP.NET Core gRPC sunucusu genellikle gRPC şablonundan oluşturulur. Şablon tarafından oluşturulan proje dosyası SDK olarak kullanır Microsoft.NET.SDK.Web :

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

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

</Project>

Microsoft.NET.SDK.Web SDK değeri, ASP.NET Core çerçevesine otomatik olarak bir başvuru ekler. Başvuru, uygulamanın bir sunucuyu barındırmak için gereken ASP.NET Core türlerini kullanmasına olanak tanır.

Aşağıdaki proje dosyası ayarlarıyla non-ASP.NET Core projelerine bir gRPC sunucusu ekleyebilirsiniz:

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

Önceki proje dosyası:

  • Microsoft.NET.SDK.Web SDK olarak kullanılmaz.
  • Microsoft.AspNetCore.App öğesine bir çerçeve başvurusu ekler.
    • Çerçeve başvurusu, Windows Hizmetleri, WPF uygulamaları veya WinForms uygulamaları gibi non-ASP.NET Core uygulamalarının ASP.NET Core API'lerini kullanmasına olanak tanır.
    • Uygulama artık bir ASP.NET Core sunucusu başlatmak için ASP.NET Core API'lerini kullanabilir.
  • gRPC gereksinimlerini ekler:

Daha fazla bilgi için Microsoft.AspNetCore.App çerçeve başvurusunu kullanmayla ilgili olarak, ASP.NET Core paylaşılan çerçevesini kullanma konusuna bakın.

ASP.NET Core API'leriyle tümleştirme

gRPC hizmetleri, Bağımlılık Enjeksiyonu (DI) ve Günlükleme gibi ASP.NET Core özelliklerine tam erişime sahiptir. Örneğin, hizmet uygulaması oluşturucu aracılığıyla DI kapsayıcısından bir günlükçü hizmetini çözümleyebilir:

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

Varsayılan olarak, gRPC hizmeti uygulaması diğer DI hizmetlerini herhangi bir yaşam süresiyle (Tekil, Kapsamlı veya Geçici) çözümleyebilir.

gRPC yöntemlerinde HttpContext'i çözme

gRPC API'si yöntem, konak, üst bilgi ve fragmanlar gibi bazı HTTP/2 ileti verilerine erişim sağlar. Erişim, her gRPC yöntemine geçirilen ServerCallContext bağımsız değişkeni ile sağlanır.

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

ServerCallContext, tüm ASP.NET API'lerinde HttpContext'e tam erişim sağlamaz. ASP.NET API'lerinde temel alınan HTTP/2 iletisini temsil eden GetHttpContext aracılığıyla HttpContext uzantı yöntemine tam erişim sağlar.

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

Ek kaynaklar

Bu belgede, ASP.NET Core kullanarak gRPC hizmetlerini kullanmaya başlama gösterilmektedir.

Önkoşullar

ASP.NET Core’da gRPC hizmeti ile çalışmaya başlama

Örnek kodu görüntüleme veya indirme (indirme).

gRPC projesi oluşturma hakkında ayrıntılı yönergeler için bkz . gRPC hizmetlerini kullanmaya başlama.

ASP.NET Core uygulamasına gRPC hizmeti ekleme

gRPC, Grpc.AspNetCore paketini gerektirir.

gRPC'yi yapılandırma

Startup.cs içinde:

  • AddGrpc yöntemiyle gRPC etkinleştirilir.
  • Her bir gRPC hizmeti, MapGrpcService yöntemi aracılığıyla yönlendirme işlem hattına eklenir.
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>();
        });
    }
}

Kod açıklamalarının İngilizce dışındaki dillere çevirisini görmek isterseniz, bunu bu GitHub tartışma konusunda bize bildirin.

ASP.NET Core ara yazılımı ve özellikleri yönlendirme işlem hattını paylaşır, bu nedenle bir uygulama ek istek işleyicileri sunmak üzere yapılandırılabilir. MVC denetleyicileri gibi ek istek işleyicileri, yapılandırılan gRPC hizmetleriyle paralel olarak çalışır.

Sunucu seçenekleri

gRPC hizmetleri tüm yerleşik ASP.NET Core sunucuları tarafından barındırılabilir.

  • Kestrel
  • Test Sunucusu
  • IIS†
  • HTTP.sys†

†.NET 5 ve Windows 11 Build 22000 veya Windows Server 2022 Build 20348 ya da daha sonraki sürümlerin gerektirir.

ASP.NET Core uygulaması için doğru sunucuyu seçme hakkında daha fazla bilgi için bkz . ASP.NET Core'da Web sunucusu uygulamaları.

Kestrel

Kestrel ASP.NET Core için platformlar arası bir web sunucusudur. Kestrel yüksek performans ve bellek kullanımına odaklanır, ancak HTTP.sys bağlantı noktası paylaşımı gibi bazı gelişmiş özelliklere sahip değildir.

Kestrel gRPC uç noktaları:

  • HTTP/2 gerektir.
  • Aktarım Katmanı Güvenliği (TLS) ile güvenliği sağlanmalıdır.

HTTP/2

gRPC http/2 gerektirir. ASP.NET Core için gRPC, HttpRequest.Protocol'unHTTP/2.

Kestrel çoğu modern işletim sisteminde HTTP/2'i destekler. Kestrel uç noktaları varsayılan olarak HTTP/1.1 ve HTTP/2 bağlantılarını destekleyecek şekilde yapılandırılır.

TLS

Kestrel gRPC için kullanılan uç noktaların güvenliği TLS ile sağlanmalıdır. Geliştirme aşamasında, ASP.NET Core geliştirme sertifikası mevcut olduğunda TLS ile güvenliği sağlanan bir uç nokta otomatik olarak oluşturulur https://localhost:5001 . Yapılandırma gerekmez. Ön https ek, uç noktanın Kestrel TLS kullandığını doğrular.

Üretimde TLS açıkça yapılandırılmalıdır. Aşağıdaki appsettings.json örnekte, TLS ile güvenliği sağlanan bir HTTP/2 uç noktası sağlanır:

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

Alternatif olarak, Kestrel uç noktalar Program.cs üzerinde yapılandırılabilir.

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

TLS'yi ile Kestreletkinleştirme hakkında daha fazla bilgi için bkz Kestrel . HTTPS uç noktası yapılandırması.

Protokol anlaşması

TLS, iletişimin güvenliğini sağlamaktan daha fazlası için kullanılır. TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışması, bir uç nokta birden çok protokolü desteklediğinde istemci ile sunucu arasında bağlantı protokolü anlaşması yapmak için kullanılır. Bu anlaşma, bağlantının HTTP/1.1 mi yoksa HTTP/2 mi kullandığını belirler.

BIR HTTP/2 uç noktası TLS olmadan yapılandırıldıysa, uç noktanın ListenOptions.Protocols değeri olarak HttpProtocols.Http2ayarlanmalıdır. Örneğin, HttpProtocols.Http1AndHttp2 birden çok protokole sahip bir uç nokta, anlaşma olmadığından TLS olmadan kullanılamaz. Güvenli olmayan uç noktaya yapılan tüm bağlantılar varsayılan olarak HTTP/1.1'dir ve gRPC çağrıları başarısız olur.

ile KestrelHTTP/2 ve TLS'yi etkinleştirme hakkında daha fazla bilgi için bkz Kestrel . uç nokta yapılandırması.

Not

macOS, .NET 8 öncesi TLS ile ASP.NET Core gRPC'leri desteklemez. .NET 7 veya önceki sürümleri kullanırken macOS üzerinde gRPC hizmetlerini başarıyla çalıştırmak için ek yapılandırma gereklidir. Daha fazla bilgi için bkz . macOS üzerinde ASP.NET Core gRPC uygulaması başlatılamıyor.

non-ASP.NET Core projelerinde gRPC barındırma

bir ASP.NET Core gRPC sunucusu genellikle gRPC şablonundan oluşturulur. Şablon tarafından oluşturulan proje dosyası SDK olarak kullanır Microsoft.NET.SDK.Web :

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

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

</Project>

Microsoft.NET.SDK.Web SDK değeri, ASP.NET Core çerçevesine otomatik olarak bir başvuru ekler. Başvuru, uygulamanın bir sunucuyu barındırmak için gereken ASP.NET Core türlerini kullanmasına olanak tanır.

Aşağıdaki proje dosyası ayarlarıyla non-ASP.NET Core projelerine bir gRPC sunucusu ekleyebilirsiniz:

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

Önceki proje dosyası:

  • Microsoft.NET.SDK.Web SDK olarak kullanılmaz.
  • Microsoft.AspNetCore.App öğesine bir çerçeve referansı ekler.
    • Çerçeve başvurusu, Windows Hizmetleri, WPF uygulamaları veya WinForms uygulamaları gibi non-ASP.NET Core uygulamalarının ASP.NET Core API'lerini kullanmasına olanak tanır.
    • Uygulama artık bir ASP.NET Core sunucusu başlatmak için ASP.NET Core API'lerini kullanabilir.
  • gRPC gereksinimlerini ekler:

Çerçeve referansını Microsoft.AspNetCore.App kullanma hakkında daha fazla bilgi için bkz: ASP.NET Core paylaşılan çerçevesini kullanma bölümü.

ASP.NET Core API'leriyle tümleştirme

gRPC hizmetleri, Bağımlılık Enjeksiyonu (DI) ve Günlük (Logging) gibi ASP.NET Core özelliklerine tam erişime sahiptir. Örneğin, hizmet uygulaması oluşturucu aracılığıyla DI kapsayıcısından bir günlükçü hizmetini çözümleyebilir:

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

Varsayılan olarak, gRPC hizmeti uygulaması diğer DI hizmetlerini herhangi bir yaşam süresiyle (Tekil, Kapsamlı veya Geçici) çözümleyebilir.

gRPC yöntemlerinde HttpContext'i çözme

gRPC API'si yöntem, konak, üst bilgi ve fragmanlar gibi bazı HTTP/2 ileti verilerine erişim sağlar. Erişim, ServerCallContext her gRPC yöntemine geçirilen bağımsız değişken aracılığıyla sağlanır.

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

ServerCallContext, tüm ASP.NET API'lerinde HttpContext için tam erişim sağlamaz. uzantı yöntemi, GetHttpContext ASP.NET API'lerinde temel alınan HTTP/2 iletisini temsil edene tam erişim HttpContext sağlar:

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

Ek kaynaklar

Bu belgede, ASP.NET Core kullanarak gRPC hizmetlerini kullanmaya başlama gösterilmektedir.

Önkoşullar

ASP.NET Core’da gRPC hizmeti ile çalışmaya başlama

Örnek kodu görüntüleme veya indirme (indirme).

gRPC projesi oluşturma hakkında ayrıntılı yönergeler için bkz . gRPC hizmetlerini kullanmaya başlama.

ASP.NET Core uygulamasına gRPC hizmeti ekleme

gRPC, Grpc.AspNetCore paketini gerektirir.

gRPC'yi yapılandırma

Startup.cs içinde:

  • AddGrpc yöntemi kullanılarak gRPC etkinleştirilir.
  • Her bir gRPC hizmeti MapGrpcService yöntemi aracılığıyla yönlendirme işlem hattına eklenir.
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>();
        });
    }
}

Kod açıklamalarının İngilizce dışındaki dillere çevirisini görmek isterseniz, bunu bu GitHub tartışma konusunda bize bildirin.

ASP.NET Core ara yazılımı ve özellikleri yönlendirme işlem hattını paylaşır, bu nedenle bir uygulama ek istek işleyicileri sunmak üzere yapılandırılabilir. MVC denetleyicileri gibi ek istek işleyicileri, yapılandırılan gRPC hizmetleriyle paralel olarak çalışır.

Sunucu seçenekleri

gRPC hizmetleri tüm yerleşik ASP.NET Core sunucuları tarafından barındırılabilir.

  • Kestrel
  • TestSunucusu
  • IIS†
  • HTTP.sys†

.NET 5 ve Windows 11 Yapı 22000 veya Windows Server 2022 Yapı 20348 veya daha yenisini gerektirir.

ASP.NET Core uygulaması için doğru sunucuyu seçme hakkında daha fazla bilgi için bkz . ASP.NET Core'da Web sunucusu uygulamaları.

Kestrel

Kestrel ASP.NET Core için platformlar arası bir web sunucusudur. Kestrel yüksek performans ve bellek kullanımına odaklanır, ancak HTTP.sys bağlantı noktası paylaşımı gibi bazı gelişmiş özelliklere sahip değildir.

Kestrel gRPC uç noktaları:

  • HTTP/2 gerektir.
  • Aktarım Katmanı Güvenliği (TLS) ile güvenliği sağlanmalıdır.

HTTP/2

gRPC http/2 gerektirir. ASP.NET Core için gRPC, HttpRequest.Protocol'unHTTP/2.

Kestrel çoğu modern işletim sisteminde HTTP/2'i destekler. Kestrel uç noktaları varsayılan olarak HTTP/1.1 ve HTTP/2 bağlantılarını destekleyecek şekilde yapılandırılır.

TLS

Kestrel gRPC için kullanılan uç noktaların güvenliği TLS ile sağlanmalıdır. Geliştirme aşamasında, ASP.NET Core geliştirme sertifikası mevcut olduğunda TLS ile güvenliği sağlanan bir uç nokta otomatik olarak oluşturulur https://localhost:5001 . Yapılandırma gerekmez. Ön https ek, uç noktanın Kestrel TLS kullandığını doğrular.

Üretimde TLS açıkça yapılandırılmalıdır. Aşağıdaki appsettings.json örnekte, TLS ile güvenliği sağlanan bir HTTP/2 uç noktası sağlanır:

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

Alternatif olarak, Kestrel uç noktalar Program.cs içinde yapılandırılabilir.

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

TLS'yi ile Kestreletkinleştirme hakkında daha fazla bilgi için bkz Kestrel . HTTPS uç noktası yapılandırması.

Protokol anlaşması

TLS, iletişimin güvenliğini sağlamaktan daha fazlası için kullanılır. TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışması, bir uç nokta birden çok protokolü desteklediğinde istemci ile sunucu arasında bağlantı protokolü anlaşması yapmak için kullanılır. Bu anlaşma, bağlantının HTTP/1.1 mi yoksa HTTP/2 mi kullandığını belirler.

BIR HTTP/2 uç noktası TLS olmadan yapılandırıldıysa, uç noktanın ListenOptions.Protocols değeri olarak HttpProtocols.Http2ayarlanmalıdır. Örneğin, HttpProtocols.Http1AndHttp2 birden çok protokole sahip bir uç nokta, anlaşma olmadığından TLS olmadan kullanılamaz. Güvenli olmayan uç noktaya yapılan tüm bağlantılar varsayılan olarak HTTP/1.1'dir ve gRPC çağrıları başarısız olur.

ile KestrelHTTP/2 ve TLS'yi etkinleştirme hakkında daha fazla bilgi için bkz Kestrel . uç nokta yapılandırması.

Not

macOS, .NET 8 öncesi TLS ile ASP.NET Core gRPC'leri desteklemez. .NET 7 veya önceki sürümleri kullanırken macOS üzerinde gRPC hizmetlerini başarıyla çalıştırmak için ek yapılandırma gereklidir. Daha fazla bilgi için bkz . macOS üzerinde ASP.NET Core gRPC uygulaması başlatılamıyor.

non-ASP.NET Core projelerinde gRPC barındırma

bir ASP.NET Core gRPC sunucusu genellikle gRPC şablonundan oluşturulur. Şablon tarafından oluşturulan proje dosyası SDK olarak kullanır Microsoft.NET.SDK.Web :

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

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

</Project>

Microsoft.NET.SDK.Web SDK değeri, ASP.NET Core çerçevesine otomatik olarak bir başvuru ekler. Başvuru, uygulamanın bir sunucuyu barındırmak için gereken ASP.NET Core türlerini kullanmasına olanak tanır.

Aşağıdaki proje dosyası ayarlarıyla non-ASP.NET Core projelerine bir gRPC sunucusu ekleyebilirsiniz:

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

Önceki proje dosyası:

  • Microsoft.NET.SDK.Web SDK olarak kullanılmaz.
  • Microsoft.AspNetCore.App öğesine bir çerçeve başvurusu ekler.
    • Çerçeve başvurusu, Windows Hizmetleri, WPF uygulamaları veya WinForms uygulamaları gibi non-ASP.NET Core uygulamalarının ASP.NET Core API'lerini kullanmasına olanak tanır.
    • Uygulama artık bir ASP.NET Core sunucusu başlatmak için ASP.NET Core API'lerini kullanabilir.
  • gRPC gereksinimlerini ekler:

Microsoft.AspNetCore.App çerçeve başvurusunu kullanma hakkında daha fazla bilgi için, ASP.NET Core paylaşılan çerçevesini kullanma konusuna bakın.

ASP.NET Core API'leriyle tümleştirme

gRPC hizmetleri, Bağımlılık Enjeksiyonu (DI) ve Günlük Kaydı gibi ASP.NET Core özelliklerine tam erişime sahiptir. Örneğin, hizmet uygulaması oluşturucu aracılığıyla DI kapsayıcısından bir günlükçü hizmetini çözümleyebilir:

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

Varsayılan olarak, gRPC hizmeti uygulaması diğer DI hizmetlerini herhangi bir yaşam süresiyle (Tekil, Kapsamlı veya Geçici) çözümleyebilir.

gRPC yöntemlerinde HttpContext'i çözme

gRPC API'si yöntem, konak, üst bilgi ve fragmanlar gibi bazı HTTP/2 ileti verilerine erişim sağlar. Erişim, her gRPC yöntemine geçirilen ServerCallContext bağımsız değişkeni ile sağlanır.

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

ServerCallContext, tüm ASP.NET API'lerinde HttpContext için tam erişim sağlamaz. GetHttpContext uzantı yöntemi, ASP.NET API'lerinde temel alınan HTTP/2 iletisini temsil eden HttpContext'e tam erişim sağlar.

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

Ek kaynaklar