Перенос gRPC с C-core на gRPC для .NET

В связи с реализацией базового стека не все функции работают одинаково в приложениях gRPC на основе C-core и gRPC для .NET. В этом документе описываются основные различия между двумя стеками в целях миграции.

Внимание

gRPC C-core находится в режиме обслуживания и будет заменяться gRPC для .NET. Использовать gRPC C-core для новых приложений не рекомендуется.

Поддержка платформы

gRPC C-Core и gRPC для .NET поддерживают разные платформы:

• gRPC C-core — реализация C++ gRPC с собственными стеками TLS и HTTP/2. Пакет Grpc.Core — это оболочка .NET для GRPC C-core, которая содержит сервер и клиент gRPC. Он поддерживает .NET Framework, .NET Core и .NET 5 или более поздних версий.
• gRPC для .NET — используется для .NET Core 3.x и .NET 5 или более поздних версий. В нем используются стеки TLS и HTTP/2, встроенные в современные выпуски .NET. Пакет Grpc.AspNetCore содержит сервер gRPC, размещенный в ASP.NET Core, и требует .NET Core 3.x или .NET 5 или более поздних версий. Пакет Grpc.Net.Client содержит клиент gRPC. Клиент в Grpc.Net.Client имеет ограниченную поддержку .NET Framework с использованием WinHttpHandler.

Дополнительные сведения см. в статье Поддерживаемые платформы gRPC в .NET.

Настройка сервера и канала

При переходе с gRPC C-Core на gRPC для .NET нужно изменить пакеты NuGet, конфигурацию и код запуска.

gRPC для .NET имеет отдельные пакеты NuGet для клиента и сервера. Добавленные пакеты зависят от того, размещены ли в приложении службы gRPC или оно вызывает их:

• Grpc.AspNetCore — службы размещены в ASP.NET Core. Сведения о конфигурации сервера см. в статье Службы gRPC в ASP.NET Core.
• Grpc.Net.Client — клиенты используют GrpcChannel, которые внутри себя используют сетевые функции, встроенные в .NET. Сведения о конфигурации клиента см. в статье Вызов служб gRPC с помощью клиента .NET.

После завершения миграции удалите пакет Grpc.Core из приложения. Grpc.Core содержит большие собственные двоичные файлы, а удаление пакета сокращает время восстановления NuGet и размер приложения.

Службы и клиенты, созданные кодом

gRPC C-Core и gRPC для .NET совместно используют большое количество API, а код, созданный из файлов .proto, совместим с реализациями gRPC. Большинство клиентов и служб можно перенести из C-Core в gRPC для .NET без изменений.

Время существования реализации службы gRPC

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

Ограниченное время существования позволяет реализации службы разрешать другие службы с ограниченным временем существования. Например, ограниченное время существования может также разрешать DbContext из контейнера DI посредством внедрения конструктора. Использование ограниченного времени существования:

• Новый экземпляр реализации службы создается для каждого запроса.
• Невозможно совместно использовать состояние между запросами через члены экземпляра в типе реализации.
• Общие состояния должны храниться в отдельной службе в контейнере DI. Хранимые общие состояния разрешаются в конструкторе реализации службы gRPC.

Дополнительные сведения о времени существования службы см. в статье Внедрение зависимостей в ASP.NET Core.

Добавление отдельной службы

Чтобы упростить переход от реализации gRPC C-Core к ASP.NET Core, можно изменить время существования реализации службы с ограниченного на отдельное. Для этого необходимо добавить экземпляр реализации службы в контейнер DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
    services.AddSingleton(new GreeterService());
}

Однако реализация службы с отдельным временем существования больше не может разрешать службы с заданной областью посредством внедрения конструктора.

Настройка параметров служб gRPC

В приложениях на основе C-Core такие параметры, как grpc.max_receive_message_length и grpc.max_send_message_length, настраиваются с помощью ChannelOption при создании экземпляра сервера.

В ASP.NET Core gRPC предоставляет конфигурацию с помощью типа GrpcServiceOptions. Например, максимальный размер входящего сообщения службы gRPC можно настроить с помощью AddGrpc. В следующем примере показано изменение MaxReceiveMessageSize по умолчанию с 4 на 16 МБ:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc(options =>
    {
        options.MaxReceiveMessageSize = 16 * 1024 * 1024; // 16 MB
    });
}

Дополнительные сведения о конфигурации см. в статье Конфигурация gRPC для .NET.

Ведение журнала

Приложения на основе C-Core используют GrpcEnvironment для настройки средства ведения журнала в целях отладки. Стек ASP.NET Core обеспечивает эти функции с помощью API ведения журнала. Например, средство ведения журнала можно добавить в службу gRPC посредством внедрения конструктора:

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

Дополнительные сведения о ведении журналов и диагностике gRPC см. в статье Ведение журналов и диагностика в gRPC для .NET.

HTTPS

Приложения на основе C-Core настраивают HTTPS через свойство Server.Ports. Аналогичная концепция используется для настройки серверов в ASP.NET Core. Например, для этой функции Kestrel использует конфигурацию конечной точки.

Перехватчики gRPC

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

Дополнительные сведения о сравнении этих функций с другими см. в разделе ПО промежуточного слоя и перехватчики gRPC.

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

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

Сервер gRPC можно разместить в non-ASP.NET основных проектов, добавив <FrameworkReference Include="Microsoft.AspNetCore.App" /> в проект. Справочник по платформе делает ASP.NET основные API доступны и их можно использовать для запуска сервера ASP.NET Core.

Дополнительные сведения см. в разделе Host gRPC в проектах non-ASP.NET Core.

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

• Общие сведения о gRPC на .NET
• Службы gRPC на языке C#
• Службы gRPC с ASP.NET Core
• Создание клиента и сервера gRPC для .NET Core в ASP.NET Core