Aracılığıyla paylaş


ASP.NET Core içeren gRPC Hizmetleri

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 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 8 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 8 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 yöntemiyle AddGrpc etkinleştirilir.
  • Her gRPC hizmeti yöntemi aracılığıyla yönlendirme işlem hattına MapGrpcService 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 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya sonraki sürümlerini alır.

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'un olduğunu HTTP/2doğrular.

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 içinde Program.csyapı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ı:

  • SDK olarak kullanmaz Microsoft.NET.SDK.Web .
  • öğesine Microsoft.AspNetCore.Appbir ç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:

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

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

gRPC hizmetleri, Bağımlılık Ekleme (DI) ve Günlüğe Kaydetme 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. Access, her gRPC yöntemine geçirilen bağımsız değişkenden geçer ServerCallContext :

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 tam erişim HttpContext 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

Program.cs içinde:

  • gRPC yöntemiyle AddGrpc etkinleştirilir.
  • Her gRPC hizmeti yöntemi aracılığıyla yönlendirme işlem hattına MapGrpcService 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 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya sonraki sürümlerini alır.

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'un olduğunu HTTP/2doğrular.

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 içinde Program.csyapı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ı:

  • SDK olarak kullanmaz Microsoft.NET.SDK.Web .
  • öğesine Microsoft.AspNetCore.Appbir ç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:

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

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

gRPC hizmetleri, Bağımlılık Ekleme (DI) ve Günlüğe Kaydetme 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. Access, her gRPC yöntemine geçirilen bağımsız değişkenden geçer ServerCallContext :

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 tam erişim HttpContext 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

Program.cs içinde:

  • gRPC yöntemiyle AddGrpc etkinleştirilir.
  • Her gRPC hizmeti yöntemi aracılığıyla yönlendirme işlem hattına MapGrpcService 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 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya sonraki sürümlerini alır.

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'un olduğunu HTTP/2doğrular.

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 içinde Program.csyapı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ı:

  • SDK olarak kullanmaz Microsoft.NET.SDK.Web .
  • öğesine Microsoft.AspNetCore.Appbir ç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:

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

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

gRPC hizmetleri, Bağımlılık Ekleme (DI) ve Günlüğe Kaydetme 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. Access, her gRPC yöntemine geçirilen bağımsız değişkenden geçer ServerCallContext :

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 tam erişim HttpContext 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:

  • gRPC yöntemiyle AddGrpc etkinleştirilir.
  • Her gRPC hizmeti yöntemi aracılığıyla yönlendirme işlem hattına MapGrpcService 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
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya sonraki sürümlerini alır.

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'un olduğunu HTTP/2doğrular.

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 içinde Program.csyapı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 . 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ı:

  • SDK olarak kullanmaz Microsoft.NET.SDK.Web .
  • öğesine Microsoft.AspNetCore.Appbir ç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:

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

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

gRPC hizmetleri, Bağımlılık Ekleme (DI) ve Günlüğe Kaydetme 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. Access, her gRPC yöntemine geçirilen bağımsız değişkenden geçer ServerCallContext :

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 tam erişim HttpContext 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:

  • gRPC yöntemiyle AddGrpc etkinleştirilir.
  • Her gRPC hizmeti yöntemi aracılığıyla yönlendirme işlem hattına MapGrpcService 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
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya sonraki sürümlerini alır.

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'un olduğunu HTTP/2doğrular.

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 içinde Program.csyapı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ı:

  • SDK olarak kullanmaz Microsoft.NET.SDK.Web .
  • öğesine Microsoft.AspNetCore.Appbir ç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:

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

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

gRPC hizmetleri, Bağımlılık Ekleme (DI) ve Günlüğe Kaydetme 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. Access, her gRPC yöntemine geçirilen bağımsız değişkenden geçer ServerCallContext :

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 tam erişim HttpContext 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:

  • gRPC yöntemiyle AddGrpc etkinleştirilir.
  • Her gRPC hizmeti yöntemi aracılığıyla yönlendirme işlem hattına MapGrpcService 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
  • TestServer
  • IIS†
  • HTTP.sys†

†.NET 5 ve Windows 11 Derleme 22000 veya Windows Server 2022 Derleme 20348 veya sonraki sürümlerini alır.

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'un olduğunu HTTP/2doğrular.

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 içinde Program.csyapı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ı:

  • SDK olarak kullanmaz Microsoft.NET.SDK.Web .
  • öğesine Microsoft.AspNetCore.Appbir ç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:

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

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

gRPC hizmetleri, Bağımlılık Ekleme (DI) ve Günlüğe Kaydetme 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. Access, her gRPC yöntemine geçirilen bağımsız değişkenden geçer ServerCallContext :

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 tam erişim HttpContext 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