ASP.NET Core içeren gRPC Hizmetleri

  • Makale
  • Okumak için 3 dakika

Bu belgede, ASP.NET Core kullanarak gRPC hizmetlerini kullanmaya başlamayı ASP.NET Core.

Uyarı

ASP.NET Core GRPC'nin, Azure App Service IIS ile birlikte Azure App Service gerekir. gRPC'nin nerede kullanılabı hakkında daha fazla bilgi için .NET'de desteklenen platformlarda gRPC bkz. .

Önkoşullar

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

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

gRPC Kullanmaya başlayın oluşturma hakkında ayrıntılı yönergeler için bkz. gRPC hizmetleriyle ilgili ayrıntılı yönergeler.

ASP.NET Core uygulamasına gRPC hizmetleri 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>();
        });
    }
}

Ingilizce dışındaki dillere çevrilmiş kod açıklamalarını görmek isterseniz, Bu GitHub tartışma sorununubize tanıyın.

ASP.NET Core yazılım ve özellikler yönlendirme işlem hattını paylaşır, bu nedenle bir uygulama ek istek işleyicileri hizmet verecek şekilde yalıtabilirsiniz. MVC denetleyicileri gibi ek istek işleyicileri, yapılandırılmış gRPC hizmetleriyle paralel olarak çalışır.

Sunucu seçenekleri

gRPC hizmetleri tüm yerleşik sunucularda ASP.NET Core barındırabilirsiniz.

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

†IIS için .NET 5 ve Windows 10 20300.1000 veya sonraki bir derleme gerekir.
‡HTTP.sys 19529 veya Windows 10 .NET 5 ve sonraki bir derleme gerektirir.

Önceki Windows 10 Derleme sürümleri, bir Windows Insider derlemesi gerektirir.

Bir uygulama için doğru sunucuyu seçme hakkında daha fazla bilgi ASP.NET Core bkz. ASP.NET Core'de web sunucusu uygulamaları .

Kestrel

Kestrel, platformlar arası bir web sunucusudur ASP.NET Core. Kestrel en iyi performansı ve bellek kullanımını sağlar, ancak bağlantı noktası paylaşımı gibi gelişmiş HTTP.sys özelliklerine sahip değil.

Kestrel gRPC uç noktaları:

HTTP/2

gRPC HTTP/2 gerektirir. ASP.NET Core için gRPC HttpRequest.Protocol olduğunu HTTP/2 doğrular.

Kestrelmodern işletim sistemlerinin çoğunda 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ğlanacak. Geliştirme aşamasında, üzerinde TLS ile güvenliği sağlanacak bir uç nokta, ASP.NET Core https://localhost:5001 sertifikası mevcut olduğunda otomatik olarak oluşturulur. Yapılandırma gerekmez. Ön https ek, uç noktanın Kestrel TLS'yi kullanıyor olduğunu doğrular.

Üretimde TLS'nin açıkça yapılandırılması gerekir. Aşağıdaki appsettings.json örnekte, TLS ile güvenliği sağlanan bir HTTP/2 uç noktası sağlanmıştı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 yalıtabilirsiniz:

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

ile TLS'yi etkinleştirme hakkında daha fazla bilgi için Kestrel 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. Bir uç nokta birden çok protokolü desteklediği zaman istemci ile sunucu arasındaki bağlantı protokolü üzerinde anlaşmak için TLS Uygulama Katmanı Protokol Anlaşması (ELEN) el sıkışması 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ılmışsa, uç noktanın ListenOptions.Protocols olarak ayarlanmış HttpProtocols.Http2 olmalıdır. Birden çok protokolü olan bir uç nokta (örneğin, ) TLS olmadan kullanılamaz HttpProtocols.Http1AndHttp2 çünkü anlaşma yoktur. Güvenliğiz uç noktayla yapılan tüm bağlantılar varsayılan olarak HTTP/1.1'tir ve gRPC çağrıları başarısız olur.

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

Not

macOS, TLS ile ASP.NET Core gRPC'yi desteklemez. macOS'ta gRPC hizmetlerini başarıyla çalıştırmak için ek yapılandırma gerekir. Daha fazla bilgi için bkz. macOS ASP.NET Core gRPC uygulaması başlatılamadı.

IIS

Internet Information Services (IIS), web uygulamalarını barındırmak için esnek, güvenli ve yönetilebilir bir Web Sunucusudur ve ASP.NET Core. IIS ile gRPC hizmetlerini barındırmak için .NET 5 ve Windows 10 Build 20300.1000 veya sonraki bir gerekir. Bu, Windows Insider derlemesi kullanımını gerektirmektedir.

IIS' nin TLS ve HTTP/2 kullanmak üzere yapılandırılması gerekir. Daha fazla bilgi için bkz. IIS ASP.NET Core HTTP/2 ile yükleme kullanma.

HTTP.sys

HTTP.sys, yalnızca ASP.NET Core çalışan bir web sunucusu Windows. HTTP.sys ile gRPC hizmetlerini barındırmak için .NET 5 ve Windows 10 Build 19529 veya sonraki bir Windows gerekir.

HTTP.sys TLS ve HTTP/2 kullanmak üzere yapılandırıldı. Daha fazla bilgi için bkz.HTTP.sys web sunucusu HTTP/2 desteği.

Kestrel

Kestrel, platformlar arası bir web sunucusudur ASP.NET Core. Kestrel en iyi performansı ve bellek kullanımını sağlar, ancak bağlantı noktası paylaşımı gibi gelişmiş HTTP.sys özelliklerine sahip değil.

Kestrel gRPC uç noktaları:

HTTP/2

gRPC HTTP/2 gerektirir. ASP.NET Core için gRPC HttpRequest.Protocol olduğunu HTTP/2 doğrular.

Kestrelmodern işletim sistemlerinin çoğunda 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ğlanacak. Geliştirme aşamasında, üzerinde TLS ile güvenliği sağlanacak bir uç nokta, ASP.NET Core https://localhost:5001 sertifikası mevcut olduğunda otomatik olarak oluşturulur. Yapılandırma gerekmez. Ön https ek, uç noktanın Kestrel TLS'yi kullanıyor olduğunu doğrular.

Üretimde TLS'nin açıkça yapılandırılması gerekir. Aşağıdaki appsettings.json örnekte, TLS ile güvenliği sağlanan bir HTTP/2 uç noktası sağlanmıştı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 yalıtabilirsiniz:

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

ile TLS'yi etkinleştirme hakkında daha fazla bilgi için Kestrel 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. Bir uç nokta birden çok protokolü desteklediği zaman istemci ile sunucu arasındaki bağlantı protokolü üzerinde anlaşmak için TLS Uygulama Katmanı Protokol Anlaşması (ELEN) el sıkışması 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ılmışsa, uç noktanın ListenOptions.Protocols olarak ayarlanmış HttpProtocols.Http2 olmalıdır. Birden çok protokolü olan bir uç nokta (örneğin, ) TLS olmadan kullanılamaz HttpProtocols.Http1AndHttp2 çünkü anlaşma yoktur. Güvenliğiz uç noktayla yapılan tüm bağlantılar varsayılan olarak HTTP/1.1'tir ve gRPC çağrıları başarısız olur.

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

Not

macOS, TLS ile ASP.NET Core gRPC'yi desteklemez. macOS'ta gRPC hizmetlerini başarıyla çalıştırmak için ek yapılandırma gerekir. daha fazla bilgi için bkz. macos üzerinde grpc uygulaması ASP.NET Core başlatılamıyor.

ASP.NET Core apı 'leri ile tümleştirme

grpc hizmetleri, bağımlılık ekleme (dı) ve günlüğe kaydetmegibi ASP.NET Core özelliklerine tam erişime sahiptir. Örneğin, hizmet uygulama, Oluşturucu aracılığıyla bir günlükçü hizmetini dı kapsayıcısından çözümleyebilir:

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

Varsayılan olarak, gRPC hizmeti uygulama diğer dı hizmetlerini herhangi bir yaşam süresi (tek, kapsamlı veya geçici) ile çözümleyebilir.

GRPC yöntemlerinde HttpContext 'i çözümle

GRPC API 'SI, yöntem, ana bilgisayar, üst bilgi ve tanıtımları gibi bazı HTTP/2 ileti verilerine erişim sağlar. Erişim, ServerCallContext her gRPC yöntemine geçirilen bağımsız değişkendir:

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

ServerCallContext``HttpContexttüm ASP.NET apı 'lerinde tam erişim sağlamaz. GetHttpContextuzantı yöntemi, HttpContext ASP.NET apı 'lerinde temel alınan HTTP/2 iletisini temsil eden öğesine 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