Servizi gRPC con ASP.NET Core

  • Articolo

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

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

Prerequisiti

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

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

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

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:

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:

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

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

Prerequisiti

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

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

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

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:

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:

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

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

Prerequisiti

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

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

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

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:

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:

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

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

Prerequisiti

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

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

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

Aggiungere servizi gRPC a un'app ASP.NET Core

gRPC richiede il pacchetto Grpc.AspNetCore.

Configurare gRPC

In Startup.cs:

  • gRPC è abilitato con il AddGrpc metodo .
  • Ogni servizio gRPC viene aggiunto alla pipeline di routing tramite il MapGrpcService metodo .
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>();
        });
    }
}

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:

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:

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

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:

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

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

Prerequisiti

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

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

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

Aggiungere servizi gRPC a un'app ASP.NET Core

gRPC richiede il pacchetto Grpc.AspNetCore.

Configurare gRPC

In Startup.cs:

  • gRPC è abilitato con il AddGrpc metodo .
  • Ogni servizio gRPC viene aggiunto alla pipeline di routing tramite il MapGrpcService metodo .
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>();
        });
    }
}

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:

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:

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

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.

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:

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

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

Prerequisiti

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

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

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

Aggiungere servizi gRPC a un'app ASP.NET Core

gRPC richiede il pacchetto Grpc.AspNetCore.

Configurare gRPC

In Startup.cs:

  • gRPC è abilitato con il AddGrpc metodo .
  • Ogni servizio gRPC viene aggiunto alla pipeline di routing tramite il MapGrpcService metodo .
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>();
        });
    }
}

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:

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:

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

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.

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:

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