Uso de la plantilla de proyecto de Angular con ASP.NET Core

  • Artículo

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión .NET 8 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulte la versión .NET 8 de este artículo.

Visual Studio proporciona plantillas de proyecto para crear aplicaciones de página única (SPA) basadas en marcos de JavaScript como Angular, React y Vue que tienen un back-end de ASP.NET Core. Estas plantillas:

  • Crean una solución de Visual Studio con un proyecto de front-end y un proyecto de back-end.
  • Usan el tipo de proyecto de Visual Studio para JavaScript y TypeScript (.esproj) para el front-end.
  • Usan un proyecto de ASP.NET Core para el back-end.

Los proyectos creados mediante las plantillas de Visual Studio se pueden ejecutar desde la línea de comandos en Windows, Linux y macOS. Para ejecutar la aplicación, use dotnet run --launch-profile https para ejecutar el proyecto de servidor. Al ejecutar el proyecto de servidor, se inicia automáticamente el servidor de desarrollo de JavaScript de front-end. Actualmente se requiere el perfil de inicio https.

Tutorial de Visual Studio

Para empezar a trabajar con un proyecto de Angular, siga el tutorial Creación de una aplicación ASP.NET Core con Angular en la documentación de Visual Studio.

Para obtener más información, veaJavaScript y TypeScript en Visual Studio.

Plantillas de SPA de ASP.NET Core

Visual Studio incluye plantillas para compilar aplicaciones ASP.NET Core con un front-end de JavaScript o TypeScript. Estas plantillas están disponibles en la versión 17.8 o posterior de Visual Studio 2022 con la carga de trabajo de desarrollo web y ASP.NET instalada.

Las plantillas de Visual Studio para compilar aplicaciones ASP.NET Core con un front-end de JavaScript o TypeScript ofrecen las siguientes ventajas:

  • Eliminan la separación del proyecto para el front-end y el back-end.
  • Se mantienen al día con las versiones más recientes del marco de front-end.
  • Se integran con las herramientas de línea de comandos del marco de front-end más recientes, como Vite.
  • Plantillas para JavaScript y TypeScript (solo TypeScript para Angular).
  • Experiencia enriquecida de edición de código de JavaScript y TypeScript.
  • Integran las herramientas de compilación de JavaScript con la compilación de .NET.
  • Interfaz de usuario de administración de dependencias de npm.
  • Compatible con la depuración y la configuración de inicio de Visual Studio Code.
  • Ejecute pruebas unitarias de front-end en el Explorador de pruebas mediante marcos de prueba de JavaScript.

Plantillas de SPA de ASP.NET Core heredadas

Las versiones anteriores del SDK de .NET incluían las plantillas heredadas para compilar aplicaciones SPA con ASP.NET Core. Para obtener documentación sobre estas plantillas anteriores, vea la versión ASP.NET Core 7.0 de la información general de SPA y los artículos de Angular y React.

La plantilla de proyecto de ASP.NET Core con Angular actualizada proporciona un práctico punto de partida para las aplicaciones ASP.NET Core que usan Angular y la CLI de Angular para implementar una completa interfaz de usuario (UI) del lado cliente.

La plantilla de proyecto es equivalente a crear tanto un proyecto de ASP.NET Core que funciona como API web como un proyecto de CLI de Angular que funciona como interfaz de usuario. Esta combinación de proyectos ofrece la comodidad de hospedar ambos proyectos en un único proyecto de ASP.NET Core que se puede crear y publicar como una sola unidad.

La plantilla de proyecto no está pensada para representación del lado servidor (SSR).

Creación de una nueva aplicación

En un símbolo del sistema, cree un nuevo proyecto con el comando dotnet new angular en un directorio vacío. Por ejemplo, los siguientes comandos crean la aplicación en un directorio my-new-app y cambian a ese directorio:

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

Ejecute la aplicación desde Visual Studio o la CLI de .NET Core:

Abra el archivo .csproj generado y, desde ahí, ejecute la aplicación de la manera habitual.

El proceso de compilación restaura las dependencias npm en la primera ejecución, lo que puede tardar varios minutos. Las compilaciones posteriores son mucho más rápidas.

La plantilla de proyecto crea una aplicación ASP.NET Core y una aplicación de Angular. El uso previsto de la aplicación ASP.NET Core es el acceso a los datos, la autorización y otros problemas relativos al servidor. Por otro lado, la aplicación de Angular, que reside en el subdirectorio ClientApp está destinada a todos los problemas relacionados con la interfaz de usuario.

Adición de páginas, imágenes, estilos y módulos.

El directorio ClientApp contiene una aplicación estándar de la CLI de Angular. Consulte la documentación de Angular para más información.

Existen pequeñas diferencias entre la aplicación de Angular creada con esta plantilla y la creada con la propia CLI de Angular (mediante ng new); sin embargo, las funcionalidades de la aplicación permanecen sin cambios. La aplicación creada con la plantilla contiene un diseño basado en arranque y un ejemplo de enrutamiento básico.

Ejecución de comandos ng

En un símbolo del sistema, cambie al subdirectorio ClientApp:

cd ClientApp

Si tiene instalada la herramienta ng globalmente, puede ejecutar cualquiera de sus comandos. Por ejemplo, puede ejecutar ng lint, ng test, o cualquiera de los otros comandos de la CLI de Angular. Si bien, no es necesario ejecutar ng serve, dado que la aplicación ASP.NET Core se ocupa de atender las partes del lado cliente y servidor de la aplicación. Internamente, usa ng serve en el desarrollo.

Si no tiene instalada la herramienta ng, ejecute en su lugar npm run ng. Por ejemplo, puede ejecutar npm run ng lint o npm run ng test.

Instalar paquetes de npm

Para instalar paquetes de npm de otro fabricante, use un símbolo del sistema en el subdirectorio ClientApp. Por ejemplo:

cd ClientApp
npm install <package_name>

Publicación e implementación

En el desarrollo, la aplicación se ejecuta en modo optimizado para comodidad del desarrollador. Por ejemplo, las agrupaciones de JavaScript incluyen asignaciones de origen (de modo que, durante la depuración, puede ver el código original de TypeScript). La aplicación inspecciona los cambios en los archivos de TypeScript, HTML y CSS en el disco y, automáticamente, realiza una nueva compilación y recarga cuando observa que esos archivos han cambiado.

En producción, use una versión de la aplicación que esté optimizada para el rendimiento. Esto se configura para que tenga lugar automáticamente. Al publicar, la configuración de compilación emite una compilación Ahead Of Time (AoT) reducida del código del lado cliente. A diferencia de la compilación de desarrollo, la compilación de producción no requiere la instalación de Node.js en el servidor, a menos que haya habilitado la representación previa del lado servidor (SSR).

Puede usar métodos de implementación y hospedaje de ASP.NET Core estándar.

Ejecución de "ng serve" de manera independiente

El proyecto está configurado para iniciar su propia instancia del servidor de CLI de Angular en segundo plano cuando la aplicación ASP.NET Core se inicia en modo de desarrollo. Esto resulta útil porque no tiene que ejecutar manualmente un servidor independiente.

Sin embargo, esta configuración predeterminada tiene un inconveniente. Cada vez que modifica el código de C# y la aplicación ASP.NET Core debe reiniciarse, el servidor de CLI de Angular se reinicia. Se necesitan unos 10 segundos para iniciar la copia de seguridad. Sin realiza frecuentes modificaciones en el código de C# y no quiere esperar a que se reinicie la CLI de Angular, ejecute el servidor de la CLI de Angular externamente, con independencia del proceso de ASP.NET Core.

Para ejecutar el servidor de CLI de Angular de forma externa, cambie al subdirectorio de ClientApp en un símbolo del sistema e inicie el servidor de desarrollo de CLI de Angular:

cd ClientApp
npm start

Cuando inicie la aplicación ASP.NET Core, no se iniciará un servidor de la CLI de Angular. En su lugar, se usa la instancia que inició manualmente. Esto le permite iniciar y reiniciar con mayor rapidez. Ya no tiene que esperar a que la CLI de Angular vuelva a compilar la aplicación cliente una y otra vez.

Cuando se inicia el proxy, la dirección URL de destino y el puerto se deducen de las variables de entorno establecidas por .NET ASPNETCORE_URLS y ASPNETCORE_HTTPS_PORTS. Para establecer las direcciones URL o el puerto HTTPS, use una de las variables de entorno o cambie el valor en proxy.conf.json.

Configuración del middleware de proxy para SignalR

Para obtener más información, vea http-proxy-middleware.

Recursos adicionales

La plantilla de proyecto de Angular actualizada proporciona un práctico punto de partida para las aplicaciones ASP.NET Core que usan Angular y la CLI de Angular para implementar una completa interfaz de usuario (UI) del lado cliente.

La plantilla es equivalente a crear un proyecto de ASP.NET Core que funciona como back-end de API y un proyecto de la CLI de Angular que funciona como interfaz de usuario. La plantilla ofrece la ventaja de hospedar ambos tipos de proyecto en un único proyecto de aplicación. Por lo tanto, el proyecto de aplicación se puede compilar y publicar como una sola unidad.

Creación de una nueva aplicación

En un símbolo del sistema, cree un nuevo proyecto con el comando dotnet new angular en un directorio vacío. Por ejemplo, los siguientes comandos crean la aplicación en un directorio my-new-app y cambian a ese directorio:

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

Ejecute la aplicación desde Visual Studio o la CLI de .NET Core:

Abra el archivo .csproj generado y, desde ahí, ejecute la aplicación de la manera habitual.

El proceso de compilación restaura las dependencias npm en la primera ejecución, lo que puede tardar varios minutos. Las compilaciones posteriores son mucho más rápidas.

La plantilla de proyecto crea una aplicación ASP.NET Core y una aplicación de Angular. El uso previsto de la aplicación ASP.NET Core es el acceso a los datos, la autorización y otros problemas relativos al servidor. Por otro lado, la aplicación de Angular, que reside en el subdirectorio ClientApp está destinada a todos los problemas relacionados con la interfaz de usuario.

Adición de páginas, imágenes, estilos y módulos.

El directorio ClientApp contiene una aplicación estándar de la CLI de Angular. Consulte la documentación de Angular para más información.

Existen pequeñas diferencias entre la aplicación de Angular creada con esta plantilla y la creada con la propia CLI de Angular (mediante ng new); sin embargo, las funcionalidades de la aplicación permanecen sin cambios. La aplicación creada con la plantilla contiene un diseño basado en arranque y un ejemplo de enrutamiento básico.

Ejecución de comandos ng

En un símbolo del sistema, cambie al subdirectorio ClientApp:

cd ClientApp

Si tiene instalada la herramienta ng globalmente, puede ejecutar cualquiera de sus comandos. Por ejemplo, puede ejecutar ng lint, ng test, o cualquiera de los otros comandos de la CLI de Angular. Si bien, no es necesario ejecutar ng serve, dado que la aplicación ASP.NET Core se ocupa de atender las partes del lado cliente y servidor de la aplicación. Internamente, usa ng serve en el desarrollo.

Si no tiene instalada la herramienta ng, ejecute en su lugar npm run ng. Por ejemplo, puede ejecutar npm run ng lint o npm run ng test.

Instalar paquetes de npm

Para instalar paquetes de npm de otro fabricante, use un símbolo del sistema en el subdirectorio ClientApp. Por ejemplo:

cd ClientApp
npm install --save <package_name>

Publicación e implementación

En el desarrollo, la aplicación se ejecuta en modo optimizado para comodidad del desarrollador. Por ejemplo, las agrupaciones de JavaScript incluyen asignaciones de origen (de modo que, durante la depuración, puede ver el código original de TypeScript). La aplicación inspecciona los cambios en los archivos de TypeScript, HTML y CSS en el disco y, automáticamente, realiza una nueva compilación y recarga cuando observa que esos archivos han cambiado.

En producción, use una versión de la aplicación que esté optimizada para el rendimiento. Esto se configura para que tenga lugar automáticamente. Al publicar, la configuración de compilación emite una compilación Ahead Of Time (AoT) reducida del código del lado cliente. A diferencia de la compilación de desarrollo, la compilación de producción no requiere la instalación de Node.js en el servidor, a menos que haya habilitado la representación previa del lado servidor (SSR).

Puede usar métodos de implementación y hospedaje de ASP.NET Core estándar.

Ejecución de "ng serve" de manera independiente

El proyecto está configurado para iniciar su propia instancia del servidor de CLI de Angular en segundo plano cuando la aplicación ASP.NET Core se inicia en modo de desarrollo. Esto resulta útil porque no tiene que ejecutar manualmente un servidor independiente.

Sin embargo, esta configuración predeterminada tiene un inconveniente. Cada vez que modifica el código de C# y la aplicación ASP.NET Core debe reiniciarse, el servidor de CLI de Angular se reinicia. Se necesitan unos 10 segundos para iniciar la copia de seguridad. Sin realiza frecuentes modificaciones en el código de C# y no quiere esperar a que se reinicie la CLI de Angular, ejecute el servidor de la CLI de Angular externamente, con independencia del proceso de ASP.NET Core. Para ello:

  1. En un símbolo del sistema, cambie al subdirectorio ClientApp e inicie el servidor de desarrollo de la CLI Angular:

    cd ClientApp
npm start

    Importante

    Use npm start para iniciar el servidor de desarrollo de la CLI de Angular, no ng serve, de modo que la configuración de package.json se respete. Para pasar parámetros adicionales al servidor de la CLI de Angular, agréguelos a la línea de scripts correspondiente del archivo package.json.

  2. Modifique la aplicación ASP.NET Core para usar la instancia externa de la CLI de Angular en lugar de iniciar una de las suyas. En la clase Startup, reemplace la invocación de spa.UseAngularCliServer por lo siguiente:

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

Cuando inicie la aplicación ASP.NET Core, no se iniciará un servidor de la CLI de Angular. En su lugar, se usa la instancia que inició manualmente. Esto le permite iniciar y reiniciar con mayor rapidez. Ya no tiene que esperar a que la CLI de Angular vuelva a compilar la aplicación cliente una y otra vez.

Cuando se inicia el proxy, la dirección URL de destino y el puerto se deducen de las variables de entorno establecidas por .NET ASPNETCORE_URLS y ASPNETCORE_HTTPS_PORTS. Para establecer las direcciones URL o el puerto HTTPS, use una de las variables de entorno o cambie el valor en proxy.conf.json.

Paso de datos del código de .NET al código de TypeScript

Durante SSR, quizás quiera puede pasar datos por solicitud de la aplicación ASP.NET Core a la aplicación de Angular. Por ejemplo, podría pasar información de cookies o algo que se haya leído de una base de datos. Para ello, edite la clase Startup. En la devolución de llamada de UseSpaPrerendering, establezca un valor para options.SupplyData, como el siguiente:

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

La devolución de llamada SupplyData permite pasar datos arbitrarios y por solicitud que se pueden serializar con JSON (por ejemplo, cadenas, valores booleanos o números). El código main.server.ts los recibe como params.data. Por ejemplo, el ejemplo de código anterior pasa un valor booleano como params.data.isHttpsRequest a la devolución de llamada createServerRenderer. Se puede pasar a otras partes de la aplicación en cualquier modo admitido por Angular. Por ejemplo, vea cómo main.server.ts pasa el valor BASE_URL a cualquier componente cuyo constructor se declara para recibirlo.

Desventajas de SSR

No todas las aplicaciones se benefician de SSR. La principal ventaja es el rendimiento percibido. Los visitantes que llegan a la aplicación a través de una conexión de red lenta o en dispositivos móviles lentos verán la interfaz de usuario inicial rápidamente, incluso si tarda un rato en capturar o analizar las agrupaciones de JavaScript. Sin embargo, muchas SPA se utilizan principalmente a través de redes de empresa internas rápidas en equipos rápidos donde la aplicación aparece casi al instante.

Al mismo tiempo, la habilitación de SSR conlleva importantes desventajas: Agrega complejidad al proceso de desarrollo. El código se debe ejecutar en dos entornos diferentes: cliente y servidor (en un entorno de Node.js se invoca desde ASP.NET Core). Hay algunos aspectos a tener en cuenta:

  • SSR requiere la instalación de Node.js en los servidores de producción. En algunos escenarios de implementación esto se produce automáticamente, como Azure App Services, pero no en otros, como Azure Service Fabric.
  • Al habilitar la marca de compilación BuildServerSideRenderer, el directorio node_modules se publica. Esta carpeta contiene más de 20 000 archivos, lo que aumenta el tiempo de implementación.
  • Para ejecutar el código en un entorno de Node.js, no puede confiar en la existencia de API de JavaScript específicas del explorador como window o localStorage. Si el código (o alguna biblioteca de terceros a la que hace referencia) intenta usar estas API, obtendrá un error durante SSR. Por ejemplo, no use jQuery porque hace referencia a API específicas del explorador en muchos lugares. Para evitar errores, no use en la medida de lo posible SSR ni API o bibliotecas específicas del explorador. Puede encapsular las llamadas a estas API en comprobaciones para asegurarse de que no se invoquen durante SSR. Por ejemplo, use una comprobación como la siguiente en código de JavaScript o TypeScript:
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Configuración del middleware de proxy para SignalR

Para obtener más información, vea http-proxy-middleware.

Recursos adicionales