Usare il modello di progetto per Angular 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.

Visual Studio offre modelli di progetto per la creazione di app a pagina singola basate su framework JavaScript come Angular, React e Vue con back-end ASP.NET Core. Questi modelli:

  • Creare una soluzione di Visual Studio con un progetto front-end e un progetto back-end.
  • Usare il tipo di progetto di Visual Studio per JavaScript e TypeScript (con estensione esproj) per il front-end.
  • Usare un progetto ASP.NET Core per il back-end.

I progetti creati usando i modelli di Visual Studio possono essere eseguiti dalla riga di comando in Windows, Linux e macOS. Per eseguire l'app, usare dotnet run --launch-profile https per eseguire il progetto server. L'esecuzione del progetto server avvia automaticamente il server di sviluppo JavaScript front-end. Il https profilo di avvio è attualmente necessario.

Esercitazione su Visual Studio

Per iniziare a usare un progetto Angular, seguire l'esercitazione Creare un'app ASP.NET Core con Angular nella documentazione di Visual Studio.

Per altre informazioni, vedere JavaScript e TypeScript in Visual Studio

modelli di ASP.NET Core SPA

Visual Studio include modelli per la creazione di app ASP.NET Core con un front-end JavaScript o TypeScript. Questi modelli sono disponibili in Visual Studio 2022 versione 17.8 o successiva con il carico di lavoro ASP.NET e sviluppo Web installato.

I modelli di Visual Studio per la compilazione di app ASP.NET Core con un front-end JavaScript o TypeScript offrono i vantaggi seguenti:

  • Pulire la separazione del progetto per il front-end e il back-end.
  • Rimanere aggiornati sulle versioni più recenti del framework front-end.
  • Eseguire l'integrazione con gli strumenti da riga di comando del framework front-end più recenti, ad esempio Vite.
  • Modelli per JavaScript e TypeScript (solo TypeScript per Angular).
  • Esperienza avanzata di modifica del codice JavaScript e TypeScript.
  • Integrare gli strumenti di compilazione JavaScript con la build .NET.
  • Interfaccia utente di gestione delle dipendenze npm.
  • Compatibile con il debug e l'avvio di Visual Studio Code.
  • Eseguire unit test front-end in Esplora test usando framework di test JavaScript.

Modelli legacy ASP.NET Core SPA

Le versioni precedenti di .NET SDK includevano i modelli legacy per la compilazione di app a pagina singola con ASP.NET Core. Per la documentazione su questi modelli meno recenti, vedere la versione ASP.NET Core 7.0 della panoramica dell'applicazione a pagina singola e gli articoli su Angular e React.

Il modello di progetto ASP.NET Core con Angular offre un punto di partenza pratico per ASP.NET app Core usando Angular e l'interfaccia della riga di comando di Angular per implementare un'interfaccia utente lato client avanzata.

Il modello di progetto equivale alla creazione di un progetto ASP.NET Core per fungere da API Web e da un progetto dell'interfaccia della riga di comando di Angular da usare come interfaccia utente. Questa combinazione di progetti offre la comodità di ospitare entrambi i progetti in un singolo progetto ASP.NET Core che può essere compilato e pubblicato come singola unità.

Il modello di progetto non è destinato al rendering lato server (SSR).

Creare una nuova app

Creare un nuovo progetto da un prompt dei comandi usando il comando dotnet new angular in una directory vuota. Ad esempio, i comandi seguenti creano l'app in una my-new-app directory e passano a tale directory:

dotnet new angular -o my-new-app
cd my-new-app

Eseguire l'app da Visual Studio o dall'interfaccia della riga di comando di .NET:

Aprire il file generato ed eseguire l'app come di consueto .csproj .

Alla prima esecuzione, il processo di compilazione ripristina le dipendenze di npm. Tale operazione può richiedere alcuni minuti. Le compilazioni successive sono molto più veloci.

Il modello di progetto crea un'app ASP.NET Core e un'app Angular. L'app ASP.NET Core è destinata all'uso per l'accesso ai dati, l'autorizzazione e altri elementi sul lato server. L'app Angular, che risiede nella ClientApp sottodirectory, deve essere usata per tutti i problemi dell'interfaccia utente.

Aggiungere pagine, immagini, stili e moduli

La directory contiene un'app standard dell'interfaccia della ClientApp riga di comando di Angular. Per altre informazioni, vedere la documentazione ufficiale di Angular.

Vi sono piccole differenze tra l'app Angular creata tramite questo modello e quella creata tramite l'interfaccia della riga di comando di Angular stessa (mediante ng new). Le funzionalità dell'app restano comunque invariate. L'app creata tramite il modello contiene un layout basato su bootstrap e un esempio di routing di base.

Eseguire i comandi ng

In un prompt dei comandi passare alla ClientApp sottodirectory:

cd ClientApp

Se si dispone dello strumento ng installato globalmente, è possibile eseguire i relativi comandi. Ad esempio, è possibile eseguire ng lint, ng test o qualsiasi altro comando dell'interfaccia della riga di comando di Angular. Non è tuttavia necessario eseguire ng serve, poiché l'app ASP.NET Core si occupa della gestione sia delle parti sul lato server che di quelle sul lato client dell'app. Internamente, usa ng serve in fase di sviluppo.

Se lo strumento ng non è installato, eseguire npm run ng. Ad esempio, è possibile eseguire npm run ng lint o npm run ng test.

Installa nuovi pacchetti npm

Per installare pacchetti npm di terze parti, usare un prompt dei comandi nella ClientApp sottodirectory. Ad esempio:

cd ClientApp
npm install <package_name>

Pubblicare e distribuire

In fase di sviluppo, l'app viene eseguita in una modalità ottimizzata per gli sviluppatori. Ad esempio, i bundle JavaScript includono il mapping di origine, in modo da poter visualizzare il codice TypeScript originale durante il debug. L'app controlla le modifiche dei file TypeScript, HTML e CSS su disco, quindi esegue automaticamente la ricompilazione e il ricaricamento quando rileva modifiche dei file.

Nell'ambiente di produzione usare una versione dell'app ottimizzata per le prestazioni. Questo comportamento è configurato per l'esecuzione automatica. Quando si esegue la pubblicazione, la configurazione della build genera una compilazione minimizzata AOT (Ahead Of Time) del codice sul lato client. A differenza della compilazione di sviluppo, la compilazione di produzione non richiede Node.js per essere installato nel server (a meno che non sia stato abilitato il rendering lato server (SSR)).

È possibile usare i metodi standard di hosting e distribuzione di ASP.NET Core.

Eseguire "ng serve" in modo indipendente

Il progetto è configurato in modo da avviare in background la propria istanza del server dell'interfaccia della riga di comando di Angular all'avvio dell'app ASP.NET Core in modalità di sviluppo. Ciò risulta utile in quanto evita di dover eseguire manualmente un server distinto.

Questa configurazione predefinita presenta tuttavia uno svantaggio. Ogni volta che si modifica il codice C# ed è necessario riavviare l'app ASP.NET Core, il server dell'interfaccia della riga di comando di Angular viene riavviato. Per avviare il backup sono necessari circa 10 secondi. Se si apportano frequentemente modifiche al codice C# e non si vuole attendere il riavvio dell'interfaccia della riga di comando di Angular, eseguire il server dell'interfaccia della riga di comando di Angular esternamente, in modo indipendente dal processo ASP.NET Core.

Per eseguire il server dell'interfaccia della ClientApp riga di comando di Angular esternamente, passare alla sottodirectory in un prompt dei comandi e avviare il server di sviluppo dell'interfaccia della riga di comando di Angular:

cd ClientApp
npm start

All'avvio dell'app ASP.NET Core, questa non avvierà un server dell'interfaccia della riga di comando di Angular. Verrà invece usata l'istanza che è stata avviata manualmente. Ciò consente di velocizzare l'avvio e il riavvio. Non è più necessario attendere che l'app client venga ricompilata ogni volta dall'interfaccia della riga di comando di Angular.

Quando il proxy viene avviato, l'URL e la porta di destinazione sono dedotti dalle variabili di ambiente impostate da .NET ASPNETCORE_URLS e ASPNETCORE_HTTPS_PORTS. Per impostare gli URL o la porta HTTPS, usare una delle variabili di ambiente o modificare il valore in proxy.conf.json.

Configurare il middleware proxy per SignalR

Per altre informazioni, vedere http-proxy-middleware.

Risorse aggiuntive

Il modello di progetto aggiornato per Angular fornisce un ottimo punto di partenza per le app ASP.NET Core che usano Angular e l'interfaccia della riga di comando di Angular per implementare un'interfaccia utente avanzata sul lato client.

Il modello è equivalente alla creazione di un progetto ASP.NET Core che opera come un back-end API e un progetto per l'interfaccia della riga di comando di Angular che opera come un'interfaccia utente. Il modello offre la praticità di ospitare entrambi i tipi di progetto in un singolo progetto di app. Di conseguenza, il progetto di app può essere compilato e pubblicato come una singola unità.

Creare una nuova app

Creare un nuovo progetto da un prompt dei comandi usando il comando dotnet new angular in una directory vuota. Ad esempio, i comandi seguenti creano l'app in una my-new-app directory e passano a tale directory:

dotnet new angular -o my-new-app
cd my-new-app

Eseguire l'app da Visual Studio o dall'interfaccia della riga di comando di .NET:

Aprire il file generato ed eseguire l'app come di consueto .csproj .

Alla prima esecuzione, il processo di compilazione ripristina le dipendenze di npm. Tale operazione può richiedere alcuni minuti. Le compilazioni successive sono molto più veloci.

Il modello di progetto crea un'app ASP.NET Core e un'app Angular. L'app ASP.NET Core è destinata all'uso per l'accesso ai dati, l'autorizzazione e altri elementi sul lato server. L'app Angular, che risiede nella ClientApp sottodirectory, deve essere usata per tutti i problemi dell'interfaccia utente.

Aggiungere pagine, immagini, stili e moduli

La directory contiene un'app standard dell'interfaccia della ClientApp riga di comando di Angular. Per altre informazioni, vedere la documentazione ufficiale di Angular.

Vi sono piccole differenze tra l'app Angular creata tramite questo modello e quella creata tramite l'interfaccia della riga di comando di Angular stessa (mediante ng new). Le funzionalità dell'app restano comunque invariate. L'app creata tramite il modello contiene un layout basato su bootstrap e un esempio di routing di base.

Eseguire i comandi ng

In un prompt dei comandi passare alla ClientApp sottodirectory:

cd ClientApp

Se si dispone dello strumento ng installato globalmente, è possibile eseguire i relativi comandi. Ad esempio, è possibile eseguire ng lint, ng test o qualsiasi altro comando dell'interfaccia della riga di comando di Angular. Non è tuttavia necessario eseguire ng serve, poiché l'app ASP.NET Core si occupa della gestione sia delle parti sul lato server che di quelle sul lato client dell'app. Internamente, usa ng serve in fase di sviluppo.

Se lo strumento ng non è installato, eseguire npm run ng. Ad esempio, è possibile eseguire npm run ng lint o npm run ng test.

Installa nuovi pacchetti npm

Per installare pacchetti npm di terze parti, usare un prompt dei comandi nella ClientApp sottodirectory. Ad esempio:

cd ClientApp
npm install --save <package_name>

Pubblicare e distribuire

In fase di sviluppo, l'app viene eseguita in una modalità ottimizzata per gli sviluppatori. Ad esempio, i bundle JavaScript includono il mapping di origine, in modo da poter visualizzare il codice TypeScript originale durante il debug. L'app controlla le modifiche dei file TypeScript, HTML e CSS su disco, quindi esegue automaticamente la ricompilazione e il ricaricamento quando rileva modifiche dei file.

Nell'ambiente di produzione usare una versione dell'app ottimizzata per le prestazioni. Questo comportamento è configurato per l'esecuzione automatica. Quando si esegue la pubblicazione, la configurazione della build genera una compilazione minimizzata AOT (Ahead Of Time) del codice sul lato client. A differenza della compilazione di sviluppo, la compilazione di produzione non richiede Node.js per essere installato nel server (a meno che non sia stato abilitato il rendering lato server (SSR)).

È possibile usare i metodi standard di hosting e distribuzione di ASP.NET Core.

Eseguire "ng serve" in modo indipendente

Il progetto è configurato in modo da avviare in background la propria istanza del server dell'interfaccia della riga di comando di Angular all'avvio dell'app ASP.NET Core in modalità di sviluppo. Ciò risulta utile in quanto evita di dover eseguire manualmente un server distinto.

Questa configurazione predefinita presenta tuttavia uno svantaggio. Ogni volta che si modifica il codice C# ed è necessario riavviare l'app ASP.NET Core, il server dell'interfaccia della riga di comando di Angular viene riavviato. Per avviare il backup sono necessari circa 10 secondi. Se si apportano frequentemente modifiche al codice C# e non si vuole attendere il riavvio dell'interfaccia della riga di comando di Angular, eseguire il server dell'interfaccia della riga di comando di Angular esternamente, in modo indipendente dal processo ASP.NET Core. A questo scopo:

  1. In un prompt dei comandi passare alla sottodirectory e avviare il server di sviluppo dell'interfaccia della ClientApp riga di comando di Angular:

    cd ClientApp
npm start

    Importante

    Usare npm start per avviare il server di sviluppo dell'interfaccia della riga di comando di Angular, non ng serve, in modo che la configurazione in package.json sia rispettata. Per passare parametri aggiuntivi al server dell'interfaccia della riga di comando di Angular, aggiungerli alla riga pertinente scripts nel package.json file.

  2. Modificare l'app ASP.NET Core in modo da usare l'istanza dell'interfaccia della riga di comando di Angular esterna anziché avviarne una autonomamente. Nella classe Startup sostituire la chiamata spa.UseAngularCliServer con quanto segue:

    spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");

All'avvio dell'app ASP.NET Core, questa non avvierà un server dell'interfaccia della riga di comando di Angular. Verrà invece usata l'istanza che è stata avviata manualmente. Ciò consente di velocizzare l'avvio e il riavvio. Non è più necessario attendere che l'app client venga ricompilata ogni volta dall'interfaccia della riga di comando di Angular.

Quando il proxy viene avviato, l'URL e la porta di destinazione sono dedotti dalle variabili di ambiente impostate da .NET ASPNETCORE_URLS e ASPNETCORE_HTTPS_PORTS. Per impostare gli URL o la porta HTTPS, usare una delle variabili di ambiente o modificare il valore in proxy.conf.json.

Passare dati dal codice .NET nel codice TypeScript

Durante il rendering lato server, potrebbe essere necessario passare dati per ogni richiesta dall'app ASP.NET Core nell'app Angular. Ad esempio, è possibile passare cookie informazioni o un elemento letto da un database. A tale scopo, modificare la classe Startup. Nel callback per UseSpaPrerendering, impostare un valore per options.SupplyData come il seguente:

options.SupplyData = (context, data) =>
{
    // Creates a new value called isHttpsRequest that's passed to TypeScript code
    data["isHttpsRequest"] = context.Request.IsHttps;
};

Il callback SupplyData consente di passare dati arbitrari serializzabili con JSON per ogni richiesta, ad esempio stringhe, valori booleani o numeri. Il main.server.ts codice riceve questo valore come params.data. Ad esempio, l'esempio di codice precedente passa un valore booleano come params.data.isHttpsRequest nel callback createServerRenderer. È possibile passare questo valore ad altre parti dell'app in qualsiasi modo supportato da Angular. Ad esempio, vedere come main.server.ts passa il valore a qualsiasi componente il BASE_URL cui costruttore viene dichiarato di riceverlo.

Svantaggi del rendering lato server

Non tutte le app traggono vantaggio dal rendering lato server. Il vantaggio principale è rappresentato dalle prestazioni percepite. I visitatori che raggiungono l'app tramite una connessione di rete lenta o da dispositivi mobili lenti vedono l'interfaccia utente iniziale rapidamente, anche se occorre un certo tempo per recuperare o analizzare i bundle JavaScript. Tuttavia, molte applicazioni a pagina singola sono usate principalmente in reti aziendali interne, su computer veloci in cui l'app viene visualizzata quasi istantaneamente.

Allo stesso tempo, l'abilitazione del rendering lato server presenta alcuni svantaggi significativi. Aumenta la complessità del processo di sviluppo. Il codice deve essere eseguito in due ambienti diversi: lato client e lato server (in un ambiente Node.js richiamato da ASP.NET Core). Di seguito sono illustrati alcuni aspetti da tenere presente:

  • SSR richiede un nodo.js installazione nei server di produzione. Ciò avviene automaticamente per alcuni scenari di distribuzione, ad esempio Servizio app di Azure, ma non per altri, come Azure Service Fabric.
  • L'abilitazione del flag di compilazione BuildServerSideRenderer determina la pubblicazione della directory node_modules. Questa cartella contiene oltre 20.000 file, che aumentano il tempo di distribuzione.
  • Per eseguire il codice in un nodo.js ambiente, non può basarsi sull'esistenza di API JavaScript specifiche del browser, window ad esempio o localStorage. Se il codice (o una libreria di terze parti a cui si fa riferimento) tenta di usare queste API, verrà visualizzato un errore durante il rendering lato server. Ad esempio, non usare jQuery perché fa riferimento ad API specifiche del browser in numerose posizioni. Per evitare errori, è necessario non usare il rendering lato server o evitare API o librerie specifiche del browser. È possibile eseguire il wrapping di tutte le chiamate a tali API nei controlli per assicurarsi che non vengano richiamate durante il rendering lato server. Nel codice JavaScript o TypeScript, ad esempio, usare un controllo simile al seguente:
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Configurare il middleware proxy per SignalR

Per altre informazioni, vedere http-proxy-middleware.

Risorse aggiuntive