Службы gRPC в ASP.NET Core

Статья
11/30/2023

В этом документе показано, как приступить к работе со службами gRPC с помощью ASP.NET Core.

Необходимые компоненты

Visual Studio 2022 с рабочей нагрузкой ASP.NET и веб-разработка.

Начало работы со службой gRPC в ASP.NET Core

Просмотреть или скачать пример кода (описание скачивания).

Visual Studio
Visual Studio Code/Visual Studio для Mac

Подробные инструкции по созданию проекта gRPC см. в статье Начало работы со службами gRPC.

Добавление служб gRPC в приложение ASP.NET Core

Для gRPC требуется пакет Grpc.AspNetCore.

Настройка gRPC

В Program.cs:

gRPC включается с помощью метода AddGrpc.
Каждая служба gRPC добавляется в конвейер маршрутизации с помощью метода MapGrpcService.

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

Если вы хотите увидеть комментарии к коду, переведенные на языки, отличные от английского, сообщите нам на странице обсуждения этой проблемы на сайте GitHub.

ПО промежуточного слоя ASP.NET Core и компоненты совместно используют конвейер маршрутов, поэтому приложение можно настроить для обслуживания дополнительных обработчиков запросов. Дополнительные обработчики запросов, такие как контроллеры MVC, работают параллельно с настроенными службами gRPC.

Параметры сервера

Службы gRPC могут размещаться всеми встроенными серверами ASP.NET Core.

Kestrel
TestServer
IIS†
HTTP.sys†

†Требуется .NET 5 и Windows 11 сборки 22000 либо Windows Server 2022 сборки 20348 или более поздней версии.

Дополнительные сведения о выборе правильного сервера для приложения ASP.NET Core см. в статье Реализации веб-сервера в ASP.NET Core.

Kestrel

Kestrel — это кроссплатформенный веб-сервер для ASP.NET Core. Kestrel обеспечивает высокую производительность и эффективное использование памяти, однако в нем нет некоторых расширенных функций HTTP.sys, таких как общий доступ к портам.

Конечные точки gRPC Kestrel:

Требуется HTTP/2.
Безопасность следует обеспечивать с помощью протокола TLS.

HTTP/2

Для gRPC требуется HTTP/2. gRPC для ASP.NET Core проверяет, что HttpRequest.Protocol имеет значение HTTP/2.

Kestrelподдерживает HTTP/2 в большинстве современных операционных систем. Конечные точки Kestrel настроены для поддержки подключений HTTP/1.1 и HTTP/2 по умолчанию.

TLS

Конечные точки Kestrel, используемые для gRPC, должны быть защищены с помощью TLS. При разработке конечная точка, защищенная с помощью TLS, автоматически создается в https://localhost:5001 при наличии сертификата разработки ASP.NET Core. Настройка не требуется. Префикс https проверяет, что конечная точка Kestrel использует TLS.

В рабочей среде необходимо явно настроить TLS. В следующем примере appsettings.json предоставляется конечная точка HTTP/2, защищенная с помощью TLS:

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

Кроме того, конечные точки Kestrel можно настроить в файле Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Дополнительные сведения о включении TLS с помощью Kestrel см. в разделе Настройка конечной точки HTTPS Kestrel.

Согласование протокола

Протокол TLS используется не только для защиты обмена данными. Подтверждение установки связи TLS Application-Layer Protocol Negotiation (ALPN) используется для согласования протокола подключения между клиентом и сервером, если конечная точка поддерживает несколько протоколов. Это согласование определяет, использует ли соединение HTTP/1.1 или HTTP/2.

Если конечная точка HTTP/2 настроена без TLS, для конечной точки ListenOptions.Protocols должно быть установлено значение HttpProtocols.Http2. Конечная точка с несколькими протоколами, например HttpProtocols.Http1AndHttp2, не может использоваться без TLS, так как отсутствует согласование. Все подключения к незащищенной конечной точке по умолчанию осуществляются по протоколу HTTP/1.1, а вызовы gRPC завершаются ошибкой.

Дополнительные сведения о включении HTTP/2 и TLS с помощью Kestrel см. в разделе Настройка конечной точки Kestrel.

Примечание.

macOS не поддерживает ASP.NET Core gRPC с TLS до .NET 8. Дополнительная конфигурация необходима для успешного запуска служб gRPC в macOS при использовании .NET 7 или более ранней версии. Дополнительные сведения см. в статье Не удается запустить приложение ASP.NET Core gRPC в macOS.

IIS

Службы IIS — это гибкий, безопасный и управляемый веб-сервер для размещения веб-приложений, включая ASP.NET Core. .NET 5 и Windows 11 сборки 22000 или Windows Server 2022 сборки 20348 или более поздней версии требуются для размещения служб gRPC со службами IIS.

Службы IIS должны быть настроены для использования TLS и HTTP/2. Дополнительные сведения см. в статье Использование ASP.NET Core с HTTP/2 в службах IIS.

HTTP.sys

HTTP.sys — это веб-сервер для ASP.NET Core, который работает только в Windows. Для размещения служб gRPC с HTTP.sys требуются .NET 5 и Windows 11 сборки 22000 или более поздней версии.

HTTP.sys необходимо настроить для использования TLS и HTTP/2. Дополнительные сведения см. в разделе Поддержка HTTP/2 для веб-сервера HTTP.sys.

Размещение gRPC в проектах non-ASP.NET Core

Сервер ASP.NET Core gRPC обычно создается из шаблона gRPC. Файл проекта, созданный шаблоном, используется Microsoft.NET.SDK.Web в качестве пакета SDK:

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

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

</Project>

Значение Microsoft.NET.SDK.Web пакета SDK автоматически добавляет ссылку на платформу ASP.NET Core. Ссылка позволяет приложению использовать ASP.NET основные типы, необходимые для размещения сервера.

Вы можете добавить сервер gRPC в проекты non-ASP.NET Core со следующими параметрами файла проекта:

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

В предыдущем файле проекта выполняются следующие действия:

Не используется Microsoft.NET.SDK.Web в качестве пакета SDK.
Добавляется ссылка на платформу в Microsoft.AspNetCore.App.
- Справочник по платформе позволяет non-ASP.NET приложениям Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать ASP.NET основные API.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на Grpc.AspNetCoreпакет NuGet.
- Файл .proto.

Дополнительные сведения об использовании Microsoft.AspNetCore.App ссылки на платформу см. в разделе "Использование общей платформы ASP.NET Core".

Интеграция с API ASP.NET Core

Службы gRPC имеют полный доступ к компонентам ASP.NET Core, таким как внедрение зависимостей (DI) и ведение журнала. Например, реализация службы может разрешить службу ведения журнала из контейнера DI с помощью конструктора:

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

По умолчанию реализация службы gRPC может разрешать другие службы DI с любым временем существования (отдельное, ограниченное, временное).

Разрешение HttpContext в методах gRPC

API gRPC предоставляет доступ к некоторым данным сообщений HTTP/2, таким как метод, узел, заголовок и трейлеры. Доступ осуществляется через аргумент ServerCallContext, передаваемый в каждый метод gRPC:

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

ServerCallContext не предоставляет полный доступ к HttpContext во всех API ASP.NET. Метод расширения GetHttpContext предоставляет полный доступ к HttpContext, представляющему базовое сообщение HTTP/2 в API ASP.NET:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

Дополнительные ресурсы

В этом документе показано, как приступить к работе со службами gRPC с помощью ASP.NET Core.

Необходимые компоненты

Visual Studio 2022 с рабочей нагрузкой ASP.NET и веб-разработка.

Начало работы со службой gRPC в ASP.NET Core

Просмотреть или скачать пример кода (описание скачивания).

Visual Studio
Visual Studio Code/Visual Studio для Mac

Подробные инструкции по созданию проекта gRPC см. в статье Начало работы со службами gRPC.

Добавление служб gRPC в приложение ASP.NET Core

Для gRPC требуется пакет Grpc.AspNetCore.

Настройка gRPC

В Program.cs:

gRPC включается с помощью метода AddGrpc.
Каждая служба gRPC добавляется в конвейер маршрутизации с помощью метода MapGrpcService.

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

Параметры сервера

Службы gRPC могут размещаться всеми встроенными серверами ASP.NET Core.

Kestrel
TestServer
IIS†
HTTP.sys†

†Требуется .NET 5 и Windows 11 сборки 22000 либо Windows Server 2022 сборки 20348 или более поздней версии.

Kestrel

Конечные точки gRPC Kestrel:

Требуется HTTP/2.
Безопасность следует обеспечивать с помощью протокола TLS.

HTTP/2

Для gRPC требуется HTTP/2. gRPC для ASP.NET Core проверяет, что HttpRequest.Protocol имеет значение HTTP/2.

TLS

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

Кроме того, конечные точки Kestrel можно настроить в файле Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Дополнительные сведения о включении TLS с помощью Kestrel см. в разделе Настройка конечной точки HTTPS Kestrel.

Согласование протокола

Дополнительные сведения о включении HTTP/2 и TLS с помощью Kestrel см. в разделе Настройка конечной точки Kestrel.

Примечание.

IIS

HTTP.sys

Размещение gRPC в проектах non-ASP.NET Core

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

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

</Project>

Вы можете добавить сервер gRPC в проекты non-ASP.NET Core со следующими параметрами файла проекта:

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

В предыдущем файле проекта выполняются следующие действия:

Не используется Microsoft.NET.SDK.Web в качестве пакета SDK.
Добавляется ссылка на платформу в Microsoft.AspNetCore.App.
- Справочник по платформе позволяет non-ASP.NET приложениям Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать ASP.NET основные API.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на Grpc.AspNetCoreпакет NuGet.
- Файл .proto.

Интеграция с API ASP.NET Core

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

Разрешение HttpContext в методах gRPC

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

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

Дополнительные ресурсы

В этом документе показано, как приступить к работе со службами gRPC с помощью ASP.NET Core.

Необходимые компоненты

Visual Studio 2022 с рабочей нагрузкой ASP.NET и веб-разработка.
Пакет SDK для .NET 6.0

Начало работы со службой gRPC в ASP.NET Core

Просмотреть или скачать пример кода (описание скачивания).

Visual Studio
Visual Studio Code/Visual Studio для Mac

Подробные инструкции по созданию проекта gRPC см. в статье Начало работы со службами gRPC.

Добавление служб gRPC в приложение ASP.NET Core

Для gRPC требуется пакет Grpc.AspNetCore.

Настройка gRPC

В Program.cs:

gRPC включается с помощью метода AddGrpc.
Каждая служба gRPC добавляется в конвейер маршрутизации с помощью метода MapGrpcService.

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

Параметры сервера

Службы gRPC могут размещаться всеми встроенными серверами ASP.NET Core.

Kestrel
TestServer
IIS†
HTTP.sys†

†Требуется .NET 5 и Windows 11 сборки 22000 либо Windows Server 2022 сборки 20348 или более поздней версии.

Kestrel

Конечные точки gRPC Kestrel:

Требуется HTTP/2.
Безопасность следует обеспечивать с помощью протокола TLS.

HTTP/2

Для gRPC требуется HTTP/2. gRPC для ASP.NET Core проверяет, что HttpRequest.Protocol имеет значение HTTP/2.

TLS

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

Кроме того, конечные точки Kestrel можно настроить в файле Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

Дополнительные сведения о включении TLS с помощью Kestrel см. в разделе Настройка конечной точки HTTPS Kestrel.

Согласование протокола

Дополнительные сведения о включении HTTP/2 и TLS с помощью Kestrel см. в разделе Настройка конечной точки Kestrel.

Примечание.

IIS

HTTP.sys

Размещение gRPC в проектах non-ASP.NET Core

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

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

</Project>

Вы можете добавить сервер gRPC в проекты non-ASP.NET Core со следующими параметрами файла проекта:

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

В предыдущем файле проекта выполняются следующие действия:

Не используется Microsoft.NET.SDK.Web в качестве пакета SDK.
Добавляется ссылка на платформу в Microsoft.AspNetCore.App.
- Справочник по платформе позволяет non-ASP.NET приложениям Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать ASP.NET основные API.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на Grpc.AspNetCoreпакет NuGet.
- Файл .proto.

Интеграция с API ASP.NET Core

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

Разрешение HttpContext в методах gRPC

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

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

Дополнительные ресурсы

В этом документе показано, как приступить к работе со службами gRPC с помощью ASP.NET Core.

Необходимые компоненты

Visual Studio 2019 16.8 или более поздней версии с рабочей нагрузкой ASP.NET и разработка веб-приложений
Пакет SDK для .NET 5.0

Начало работы со службой gRPC в ASP.NET Core

Просмотреть или скачать пример кода (описание скачивания).

Visual Studio
Visual Studio Code/Visual Studio для Mac

Подробные инструкции по созданию проекта gRPC см. в статье Начало работы со службами gRPC.

Добавление служб gRPC в приложение ASP.NET Core

Для gRPC требуется пакет Grpc.AspNetCore.

Настройка gRPC

В Startup.cs:

gRPC включается с помощью метода AddGrpc.
Каждая служба gRPC добавляется в конвейер маршрутизации с помощью метода MapGrpcService.

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

Параметры сервера

Службы gRPC могут размещаться всеми встроенными серверами ASP.NET Core.

Kestrel
TestServer
IIS†
HTTP.sys†

†Требуется .NET 5 и Windows 11 сборки 22000 либо Windows Server 2022 сборки 20348 или более поздней версии.

Kestrel

Конечные точки gRPC Kestrel:

Требуется HTTP/2.
Безопасность следует обеспечивать с помощью протокола TLS.

HTTP/2

Для gRPC требуется HTTP/2. gRPC для ASP.NET Core проверяет, что HttpRequest.Protocol имеет значение HTTP/2.

TLS

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

Кроме того, конечные точки Kestrel можно настроить в файле Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Дополнительные сведения о включении TLS с помощью Kestrel см. в разделе Настройка конечной точки HTTPS Kestrel.

Согласование протокола

Дополнительные сведения о включении HTTP/2 и TLS с помощью Kestrel см. в разделе Настройка конечной точки Kestrel.

Примечание.

IIS

HTTP.sys

Размещение gRPC в проектах non-ASP.NET Core

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

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

</Project>

Вы можете добавить сервер gRPC в проекты non-ASP.NET Core со следующими параметрами файла проекта:

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

В предыдущем файле проекта выполняются следующие действия:

Не используется Microsoft.NET.SDK.Web в качестве пакета SDK.
Добавляется ссылка на платформу в Microsoft.AspNetCore.App.
- Справочник по платформе позволяет non-ASP.NET приложениям Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать ASP.NET основные API.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на Grpc.AspNetCoreпакет NuGet.
- Файл .proto.

Интеграция с API ASP.NET Core

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

Разрешение HttpContext в методах gRPC

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

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

Дополнительные ресурсы

В этом документе показано, как приступить к работе со службами gRPC с помощью ASP.NET Core.

Необходимые компоненты

Visual Studio 2019 16.4 или более поздней версии с рабочей нагрузкой ASP.NET и разработка веб-приложений
Пакет SDK для .NET Core 3.1

Начало работы со службой gRPC в ASP.NET Core

Просмотреть или скачать пример кода (описание скачивания).

Visual Studio
Visual Studio Code/Visual Studio для Mac

Подробные инструкции по созданию проекта gRPC см. в статье Начало работы со службами gRPC.

Добавление служб gRPC в приложение ASP.NET Core

Для gRPC требуется пакет Grpc.AspNetCore.

Настройка gRPC

В Startup.cs:

gRPC включается с помощью метода AddGrpc.
Каждая служба gRPC добавляется в конвейер маршрутизации с помощью метода MapGrpcService.

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

Параметры сервера

Службы gRPC могут размещаться всеми встроенными серверами ASP.NET Core.

Kestrel
TestServer
IIS†
HTTP.sys†

†Требуется .NET 5 и Windows 11 сборки 22000 либо Windows Server 2022 сборки 20348 или более поздней версии.

Kestrel

Конечные точки gRPC Kestrel:

Требуется HTTP/2.
Безопасность следует обеспечивать с помощью протокола TLS.

HTTP/2

Для gRPC требуется HTTP/2. gRPC для ASP.NET Core проверяет, что HttpRequest.Protocol имеет значение HTTP/2.

TLS

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

Кроме того, конечные точки Kestrel можно настроить в файле Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Дополнительные сведения о включении TLS с помощью Kestrel см. в разделе Настройка конечной точки HTTPS Kestrel.

Согласование протокола

Дополнительные сведения о включении HTTP/2 и TLS с помощью Kestrel см. в разделе Настройка конечной точки Kestrel.

Примечание.

Размещение gRPC в проектах non-ASP.NET Core

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

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

</Project>

Вы можете добавить сервер gRPC в проекты non-ASP.NET Core со следующими параметрами файла проекта:

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

В предыдущем файле проекта выполняются следующие действия:

Не используется Microsoft.NET.SDK.Web в качестве пакета SDK.
Добавляется ссылка на платформу в Microsoft.AspNetCore.App.
- Справочник по платформе позволяет non-ASP.NET приложениям Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать ASP.NET основные API.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на Grpc.AspNetCoreпакет NuGet.
- Файл .proto.

Интеграция с API ASP.NET Core

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

Разрешение HttpContext в методах gRPC

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

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

Дополнительные ресурсы

В этом документе показано, как приступить к работе со службами gRPC с помощью ASP.NET Core.

Необходимые компоненты

Visual Studio 2019 с рабочей нагрузкой ASP.NET и веб-разработка.
Пакет SDK для .NET Core 3.0

Начало работы со службой gRPC в ASP.NET Core

Просмотреть или скачать пример кода (описание скачивания).

Visual Studio
Visual Studio Code/Visual Studio для Mac

Подробные инструкции по созданию проекта gRPC см. в статье Начало работы со службами gRPC.

Добавление служб gRPC в приложение ASP.NET Core

Для gRPC требуется пакет Grpc.AspNetCore.

Настройка gRPC

В Startup.cs:

gRPC включается с помощью метода AddGrpc.
Каждая служба gRPC добавляется в конвейер маршрутизации с помощью метода MapGrpcService.

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

Параметры сервера

Службы gRPC могут размещаться всеми встроенными серверами ASP.NET Core.

Kestrel
TestServer
IIS†
HTTP.sys†

†Требуется .NET 5 и Windows 11 сборки 22000 либо Windows Server 2022 сборки 20348 или более поздней версии.

Kestrel

Конечные точки gRPC Kestrel:

Требуется HTTP/2.
Безопасность следует обеспечивать с помощью протокола TLS.

HTTP/2

Для gRPC требуется HTTP/2. gRPC для ASP.NET Core проверяет, что HttpRequest.Protocol имеет значение HTTP/2.

TLS

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

Кроме того, конечные точки Kestrel можно настроить в файле Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

Дополнительные сведения о включении TLS с помощью Kestrel см. в разделе Настройка конечной точки HTTPS Kestrel.

Согласование протокола

Дополнительные сведения о включении HTTP/2 и TLS с помощью Kestrel см. в разделе Настройка конечной точки Kestrel.

Примечание.

Размещение gRPC в проектах non-ASP.NET Core

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

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

</Project>

Вы можете добавить сервер gRPC в проекты non-ASP.NET Core со следующими параметрами файла проекта:

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

В предыдущем файле проекта выполняются следующие действия:

Не используется Microsoft.NET.SDK.Web в качестве пакета SDK.
Добавляется ссылка на платформу в Microsoft.AspNetCore.App.
- Справочник по платформе позволяет non-ASP.NET приложениям Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать ASP.NET основные API.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на Grpc.AspNetCoreпакет NuGet.
- Файл .proto.

Интеграция с API ASP.NET Core

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

Разрешение HttpContext в методах gRPC

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

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