Usare il modello di progetto per Angular con ASP.NET Core

Visual Studio offre modelli di progetto per la creazione di app a pagina singola basate su tecnologie JavaScript, ad esempio 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 (.esproj) per il frontend.
• 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 componente 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:

• Netta separazione tra frontend e backend.
• 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, l'avvio e la configurazione di Visual Studio Code.
• Eseguire test unitari front-end in Test Explorer usando i framework di test JavaScript.

Modelli legacy ASP.NET Core SPA

Le versioni precedenti di .NET SDK includevano quelli che sono oggi considerati modelli legacy per la creazione di app a pagina singola con ASP.NET Core. Per la documentazione su questi modelli precedenti, consultare la versione .NET 7 della panoramica SPA 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 in una directory vuota utilizzando il comando dotnet new angular da un terminale dei comandi. 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:

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 ClientApp contiene un'app standard di Angular CLI. 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. Durante lo sviluppo, utilizza internamente ng serve.

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 avvenire automaticamente. 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 l'installazione di Node.js 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 esternamente il server Angular CLI, passare alla sottodirectory ClientApp in un prompt dei comandi e avviare il server di sviluppo Angular CLI.

cd ClientApp
npm start

All'avvio dell'app ASP.NET Core, non avvierà un server Angular CLI. 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 con Angular CLI.

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

• Usare Identity per proteggere un server API Web per le SPA

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 backend API e un progetto Angular CLI che funge da 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 in una directory vuota utilizzando il comando dotnet new angular da un terminale dei comandi. 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:

Now listening on: http://localhost:<port>

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 ClientApp contiene un'app standard CLI 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

Nella finestra dei comandi, passare alla sottodirectory ClientApp:

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 durante lo 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 avvenire automaticamente. Quando pubblichi, la configurazione della build emette una compilazione minimizzata e compilata in anticipo (Ahead-of-Time, AoT) del codice lato client. A differenza della compilazione di sviluppo, la compilazione di produzione non richiede l'installazione di Node.js 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 ClientApp e avviare il server di sviluppo di Angular CLI:

   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 CLI di Angular, aggiungerli alla riga pertinente scripts nel file package.json.

2. Modifica la tua app ASP.NET Core per utilizzare l'istanza esterna della CLI di Angular invece di avviarne una propria. 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 Angular CLI. Verrà invece usata l'istanza che è stata avviata manualmente. Ciò consente di velocizzare l'avvio e il riavvio. Non è più necessario aspettare che l'Angular CLI ricompili la tua app client ogni volta.

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, potresti voler passare i dati delle singole richieste dalla tua app ASP.NET Core nella tua 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 BASE_URL valore a qualsiasi componente il cui costruttore è dichiarato per riceverlo.

Svantaggi del rendering lato server

Non tutte le app traggono vantaggio dal rendering lato server (SSR). 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 SPA sono principalmente utilizzate su reti aziendali interne e veloci, su computer rapidi dove l'app appare quasi istantaneamente.

Allo stesso tempo, l'abilitazione del CRL presenta 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'installazione Node.js 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 della flag di build BuildServerSideRenderer provoca 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 ambiente Node.js, non può basarsi sull'esistenza di API JavaScript specifiche del browser, ad esempio window 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 (Server-Side Rendering). Ad esempio, non usare jQuery perché fa riferimento ad API specifiche del browser in numerose posizioni. Per evitare errori, è necessario evitare il rendering lato server (SSR) o evitare API o librerie specifiche per il browser. È possibile racchiudere tutte le chiamate a tali API in controlli per assicurarsi che non vengano invocate durante il rendering sul 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

• Usare Identity per proteggere un server API Web per le SPA