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

Мақала
11/06/2024

Примечание.

Это не последняя версия этой статьи. Актуальная версия — см. версию этой статьи для .NET 9.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущем выпуске смотрите статью версии .NET 9.

Внимание

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

Для текущего выпуска см. версию .NET 9 этой статьи.

В этом документе показано, как приступить к работе со службами 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
Тестовый Сервер
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

Internet Information Services (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 Core, необходимые для размещения сервера.

Вы можете добавить сервер 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.
- Справочник по платформе позволяет приложениям, не использующим ASP.NET Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать API ASP.NET Core.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на пакет NuGet: Grpc.AspNetCore.
- Файл .proto.

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

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

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

Внедрение конструктора:

public class GreeterService : Greeter.GreeterBase
{
    private readonly ILogger<GreeterService> _logger;

    public GreeterService(ILogger<GreeterService> logger)
    {
        _logger = logger;
    }
}

Внедрение первичного конструктора (.NET 8 или более поздней версии):

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

По умолчанию реализация службы 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
Тестовый сервер
IIS†
HTTP.sys†

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

Kestrel

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

Требуется 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.

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

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

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

Примечание.

IIS

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

HTTP.sys

Размещение gRPC в проектах не 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>

Значение 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.
- Ссылка на платформу позволяет приложениям, не являющимся ASP.NET Core, таким как Windows Services, приложения WPF или приложения WinForms, использовать API ASP.NET Core.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на пакет NuGet Grpc.AspNetCore.
- Файл .proto.

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

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

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

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

Разрешение 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
        });
    }
}

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
Тестовый сервер
IIS†
HTTP.sys†

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

Kestrel

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

Требуется 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.

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

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

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

Примечание.

IIS

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

HTTP.sys

Размещение gRPC в проектах, не использующих 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.
- Справочник по фреймворку позволяет не ASP.NET Core приложениям, таким как службы Windows, приложения WPF или приложения WinForms, использовать ASP.NET Core API.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на пакет NuGet Grpc.AspNetCore.
- Файл .proto.

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

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

Обработка 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
        });
    }
}

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
ТестСервер
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.

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

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

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

Примечание.

IIS

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

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 Core-типы, необходимые для размещения сервера.

Вы можете добавить сервер 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.
- Фреймворк позволяет приложениям, не относящимся к ASP.NET Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать API ASP.NET Core.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на пакет NuGet Grpc.AspNetCore.
- Файл .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
Тестовый Сервер
IIS†
HTTP.sys†

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

Kestrel

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

Требуется 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.

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

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

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

Примечание.

Размещение gRPC в проектах, не основанных на 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.
- Фреймворк позволяет использовать API ASP.NET Core в приложениях, не относящихся к ASP.NET Core, таких как службы Windows, приложения WPF, или приложения WinForms.
- Теперь приложение может использовать api ASP.NET Core для запуска сервера ASP.NET Core.
Добавляет требования gRPC:
- Ссылка на пакет NuGet Grpc.AspNetCore.
- Файл .proto.

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

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

Определение 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
        });
    }
}

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
Тестовый Сервер
IIS†
HTTP.sys†

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

Kestrel

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

Требуется 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.

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

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

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

Примечание.

Развёртывание gRPC в проектах, не использующих 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 Core, необходимые для хостинга сервера.

Вы можете добавить сервер 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.
- Ссылку на платформу позволяет приложениям не на ASP.NET Core, таким как службы Windows, приложения WPF или приложения WinForms, использовать API ASP.NET Core.
- Теперь приложение может использовать 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

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

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

Предварительные условия

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

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

Настройка gRPC

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

Kestrel

HTTP/2

TLS

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

IIS

HTTP.sys

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

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

Определение HttpContext в методах gRPC

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

Предварительные требования

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

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

Настройка gRPC

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

Kestrel

HTTP/2

TLS

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

IIS

HTTP.sys

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

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

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

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

Предварительные условия

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

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

Настройка gRPC

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

Kestrel

HTTP/2

TLS

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

IIS

HTTP.sys

Размещение gRPC в проектах, не использующих ASP.NET Core

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

Обработка HttpContext в методах gRPC

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

Предварительные условия

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

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

Настройка gRPC

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

Kestrel

HTTP/2

TLS

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

IIS

HTTP.sys

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

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

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

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

Предварительные условия

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

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

Настройка gRPC

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

Kestrel

HTTP/2

TLS

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

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

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

Определение HttpContext в методах gRPC

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

Предварительные условия

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

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

Настройка gRPC

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