Servizi gRPC con ASP.NET Core

Questo documento illustra come iniziare a usare i servizi gRPC usando ASP.NET Core.

Prerequisiti

Visual Studio

• Visual Studio 2022 con il carico di lavoro Sviluppo ASP.NET e Web.

  

Visual Studio Code

• Visual Studio Code
• C# per Visual Studio Code (versione più recente)
• .NET 8.0 SDK

Le istruzioni di Visual Studio Code usano l'interfaccia della riga di comando di .NET per le funzioni di sviluppo di ASP.NET Core, ad esempio la creazione di progetti. È possibile seguire queste istruzioni in macOS, Linux o Windows e con qualsiasi editor di codice. Se si usa un editor diverso da Visual Studio Code potrebbero essere necessarie alcune modifiche minime.

Visual Studio per Mac

• Visual Studio 2022 per Mac (versione più recente)

  Importante

  Microsoft ha annunciato il ritiro di Visual Studio per Mac. Visual Studio per Mac non sarà più supportato a partire dal 31 agosto 2024. Le alternative includono:

  • Visual Studio Code con C # Dev Kit e le estensioni correlate, ad esempio .NET MAUI e Unity.
  • IDE di Visual Studio in esecuzione in Windows in una macchina virtuale in Mac.
  • IDE di Visual Studio in esecuzione in Windows in una macchina virtuale nel cloud.

  Per altre informazioni, vedere Annuncio del ritiro di Visual Studio per Mac.

Introduzione all'uso del servizio gRPC in ASP.NET Core

Visualizzare o scaricare il codice di esempio (procedura per il download).

Visual Studio

Per istruzioni dettagliate su come creare un progetto gRPC, vedere Introduzione ai servizi gRPC.

Visual Studio Code/Visual Studio per Mac

Eseguire dotnet new grpc -o GrpcGreeter dalla riga di comando.

Aggiungere servizi gRPC a un'app ASP.NET Core

gRPC richiede il pacchetto Grpc.AspNetCore.

Configurare gRPC

In Program.cs:

• gRPC è abilitato con il AddGrpc metodo .
• Ogni servizio gRPC viene aggiunto alla pipeline di routing tramite il MapGrpcService metodo .

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

Per visualizzare i commenti del codice tradotti in lingue diverse dall'inglese, segnalarlo in questo problema di discussione su GitHub.

ASP.NET middleware core e le funzionalità condividono la pipeline di routing, pertanto un'app può essere configurata per gestire gestori di richieste aggiuntivi. I gestori di richieste aggiuntivi, ad esempio i controller MVC, funzionano in parallelo con i servizi gRPC configurati.

Opzioni del server

I servizi gRPC possono essere ospitati da tutti i server ASP.NET Core predefiniti.

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

†Requires .NET 5 e Windows 11 Build 22000 o Windows Server 2022 Build 20348 o versione successiva.

Per altre informazioni sulla scelta del server appropriato per un'app ASP.NET Core, vedere Implementazioni del server Web in ASP.NET Core.

Kestrel

Kestrel è un server Web multipiattaforma per ASP.NET Core. Kestrel è incentrato sull'utilizzo elevato delle prestazioni e della memoria, ma non include alcune delle funzionalità avanzate di HTTP.sys, ad esempio la condivisione delle porte.

Kestrel Endpoint gRPC:

• Richiedi HTTP/2.
• Deve essere protetto con Transport Layer Security (TLS).

HTTP/2

gRPC richiede HTTP/2. gRPC per ASP.NET Core convalida HttpRequest.Protocol è HTTP/2.

Kestrelsupporta HTTP/2 nella maggior parte dei sistemi operativi moderni. Kestrel gli endpoint sono configurati per supportare le connessioni HTTP/1.1 e HTTP/2 per impostazione predefinita.

TLS

Kestrel gli endpoint usati per gRPC devono essere protetti con TLS. In fase di sviluppo, un endpoint protetto con TLS viene creato automaticamente quando https://localhost:5001 è presente il certificato di sviluppo ASP.NET Core. Non è richiesta alcuna configurazione. Un https prefisso verifica che l'endpoint Kestrel usi TLS.

Nell'ambiente di produzione, TLS deve essere configurato in modo esplicito. Nell'esempio seguente appsettings.json viene fornito un endpoint HTTP/2 protetto con TLS:

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

In alternativa, Kestrel gli endpoint possono essere configurati in 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>");
    });
});

Per altre informazioni sull'abilitazione di TLS con Kestrel, vedere Kestrel Configurazione dell'endpoint HTTPS.

Negoziazione del protocollo

TLS viene usato per più di proteggere la comunicazione. L'handshake TLS Application-Layer Protocol Negotiate (ALPN) viene usato per negoziare il protocollo di connessione tra il client e il server quando un endpoint supporta più protocolli. Questa negoziazione determina se la connessione usa HTTP/1.1 o HTTP/2.

Se un endpoint HTTP/2 è configurato senza TLS, l'endpoint ListenOptions.Protocols deve essere impostato su HttpProtocols.Http2. Un endpoint con più protocolli, ad HttpProtocols.Http1AndHttp2 esempio, non può essere usato senza TLS perché non esiste alcuna negoziazione. Tutte le connessioni all'endpoint non protetto sono predefinite HTTP/1.1 e le chiamate gRPC hanno esito negativo.

Per altre informazioni sull'abilitazione di HTTP/2 e TLS con Kestrel, vedere Kestrel Configurazione dell'endpoint.

Nota

macOS non supporta ASP.NET Core gRPC con TLS prima di .NET 8. È necessaria una configurazione aggiuntiva per eseguire correttamente i servizi gRPC in macOS quando si usa .NET 7 o versioni precedenti. Per altre informazioni, vedere Non è possibile avviare un'app ASP.NET Core gRPC in macOS.

IIS

Internet Information Services (IIS) è un server Web flessibile, sicuro e gestibile per l'hosting di app Web, tra cui ASP.NET Core. .NET 5 e Windows 11 Build 22000 o Windows Server 2022 Build 20348 o versioni successive sono necessari per ospitare servizi gRPC con IIS.

IIS deve essere configurato per l'uso di TLS e HTTP/2. Per altre informazioni, vedere Usare ASP.NET Core con HTTP/2 in IIS.

HTTP.sys

HTTP.sys è un server Web per ASP.NET Core che viene eseguito solo in Windows. .NET 5 e Windows 11 Build 22000 o Windows Server 2022 Build 20348 o versioni successive sono necessari per ospitare servizi gRPC con HTTP.sys.

HTTP.sys deve essere configurato per l'uso di TLS e HTTP/2. Per altre informazioni, vedere HTTP.sys supporto HTTP/2 del server Web.

Ospitare gRPC nei progetti non-ASP.NET Core

Un server ASP.NET Core gRPC viene in genere creato dal modello gRPC. Il file di progetto creato dal modello usa Microsoft.NET.SDK.Web come 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>

Il valore dell'SDK Microsoft.NET.SDK.Web aggiunge automaticamente un riferimento al framework ASP.NET Core. Il riferimento consente all'app di usare ASP.NET tipi core necessari per ospitare un server.

È possibile aggiungere un server gRPC ai progetti non-ASP.NET Core con le impostazioni del file di progetto seguenti:

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

Il file di progetto precedente:

• Non usa Microsoft.NET.SDK.Web come SDK.
• Aggiunge un riferimento al framework a Microsoft.AspNetCore.App.
  • Il riferimento al framework consente non-ASP.NET app Core, ad esempio Servizi Windows, app WPF o app WinForms per usare ASP.NET API Core.
  • L'app può ora usare ASP.NET API Core per avviare un server ASP.NET Core.
• Aggiunge i requisiti gRPC:
  • Riferimento al pacchetto NuGet a Grpc.AspNetCore.
  • File .proto.

Per altre informazioni sull'uso del Microsoft.AspNetCore.App framework di riferimento, vedere Usare il framework condiviso ASP.NET Core.

Integrazione con le API core di ASP.NET

I servizi gRPC hanno accesso completo alle funzionalità di base ASP.NET, ad esempio inserimento delle dipendenze (DI) e registrazione. Ad esempio, l'implementazione del servizio può risolvere un servizio logger dal contenitore di inserimento delle dipendenze tramite il costruttore :

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

Per impostazione predefinita, l'implementazione del servizio gRPC può risolvere altri servizi di inserimento delle dipendenze con qualsiasi durata (Singleton, Ambito o temporaneo).

Risolvere HttpContext nei metodi gRPC

L'API gRPC consente di accedere ad alcuni dati dei messaggi HTTP/2, ad esempio il metodo, l'host, l'intestazione e i trailer. L'accesso viene eseguito tramite l'argomento ServerCallContext passato a ogni metodo 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 non fornisce l'accesso completo a HttpContext in tutte le API di ASP.NET. Il GetHttpContext metodo di estensione fornisce l'accesso completo all'oggetto HttpContext che rappresenta il messaggio HTTP/2 sottostante nelle API di 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
        });
    }
}

Risorse aggiuntive

• Creare un client e un server gRPC di .NET Core in ASP.NET Core
• Panoramica di gRPC in .NET
• Servizi gRPC con C#
• Kestrel server Web in ASP.NET Core