ASP.NET Core içeren gRPC Hizmetleri
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.
Bu belgede, ASP.NET Core kullanarak gRPC hizmetlerini kullanmaya başlama gösterilmektedir.
Önkoşullar
Visual Studio 2022 ile ASP.NET ve web geliştirme iş yükü.
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/2
doğ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.cs
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.Http2
ayarlanmalı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.App
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:
- Için NuGet paket başvurusu
Grpc.AspNetCore
. .proto
dosya.
- Için NuGet paket başvurusu
Ç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
Visual Studio 2022 ile ASP.NET ve web geliştirme iş yükü.
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/2
doğ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.cs
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.Http2
ayarlanmalı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.App
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:
- Için NuGet paket başvurusu
Grpc.AspNetCore
. .proto
dosya.
- Için NuGet paket başvurusu
Ç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
- Visual Studio 2022 ile ASP.NET ve web geliştirme iş yükü.
- .NET 6.0 SDK
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/2
doğ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.cs
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.Http2
ayarlanmalı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.App
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:
- Için NuGet paket başvurusu
Grpc.AspNetCore
. .proto
dosya.
- Için NuGet paket başvurusu
Ç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
- Visual Studio 2019 16.8 ve üzeri ile ASP.NET ve web geliştirme iş yükü
- .NET 5.0 SDK
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/2
doğ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.cs
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.Http2
ayarlanmalı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.App
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:
- Için NuGet paket başvurusu
Grpc.AspNetCore
. .proto
dosya.
- Için NuGet paket başvurusu
Ç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
- Visual Studio 2019 16.4 ve üzeri ile ASP.NET ve web geliştirme iş yükü
- .NET Core 3.1 SDK
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/2
doğ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.cs
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.Http2
ayarlanmalı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.App
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:
- Için NuGet paket başvurusu
Grpc.AspNetCore
. .proto
dosya.
- Için NuGet paket başvurusu
Ç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/2
doğ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.cs
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.Http2
ayarlanmalı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.App
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:
- Için NuGet paket başvurusu
Grpc.AspNetCore
. .proto
dosya.
- Için NuGet paket başvurusu
Ç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
ASP.NET Core