Compilar código TypeScript (ASP.NET Core)

Artículo
10/31/2023

Use el paquete NuGet de TypeScript para agregar compatibilidad con TypeScript a los proyectos de ASP.NET Core. A partir de Visual Studio 2019, se recomienda usar el paquete NuGet en lugar de TypeScript SDK. El paquete NuGet de TypeScript proporciona una mayor portabilidad en diferentes plataformas y entornos.

En el caso de los proyectos de ASP.NET Core, un uso habitual del paquete NuGet es compilar TypeScript mediante la CLI de .NET Core. En escenarios de .NET, el paquete NuGet es la opción preferida y es la única manera de habilitar la compilación de TypeScript mediante comandos de la CLI de .NET Core como dotnet build y dotnet publish. Además, para la integración de MSBuild con ASP.NET Core y TypeScript, debe elegir el paquete NuGet.

Importante

En el caso de los proyectos basados en proyectos de JavaScript Project System (JSPS) o .esproj, use el paquete npm en lugar de NuGet para agregar compatibilidad con TypeScript.

Agregar compatibilidad con TypeScript con NuGet

El paquete NuGet de TypeScript agrega compatibilidad con TypeScript. Cuando se instala el paquete NuGet de TypeScript 3.2 o posterior en el proyecto, se carga la versión correspondiente del servicio de lenguaje TypeScript en el editor.

Si se instala Visual Studio, Visual Studio seleccionará automáticamente el proceso node.exe que incluye. Si no tiene instalado Node.js, se recomienda que instale la versión LTS desde el sitio web de Node.js.

Abra el proyecto de ASP.NET Core en Visual Studio.
en el Explorador de soluciones (panel derecho). Haga clic con el botón derecho en el nodo de proyecto y elija Administrar paquetes NuGet. En la pestaña Examinar, busque Microsoft.TypeScript.MSBuild y, a continuación, haga clic en Instalar para instalar el paquete.

Visual Studio agrega el paquete NuGet en el nodo Dependencias del Explorador de soluciones. La referencia de paquete siguiente se agrega a su archivo *.csproj.
```
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="3.9.7">
   <PrivateAssets>all</PrivateAssets>
   <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
```
Haga clic con el botón derecho en el nodo de proyecto y elija Agregar > Nuevo elemento. Elija el archivo de configuración JSON de TypeScript y, a continuación, haga clic en Agregar.

Si no ve todas las plantillas de elemento, seleccione Mostrar todas las plantillas y elija la plantilla de elemento.

Visual Studio agrega el archivo tsconfig.json a la raíz del proyecto. Puede usar este archivo para configurar opciones para el compilador de TypeScript.
Abra tsconfig.json y actualícelo para establecer las opciones del compilador que desee.

A continuación se muestra un ejemplo de un archivo tsconfig.json simple.
```
{
  "compilerOptions": {
    "noImplicitAny": false,
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5",
    "outDir": "wwwroot/js"
  },
  "include": [
    "scripts/**/*"
  ]
}
```
En este ejemplo:
- include indica al compilador dónde encontrar archivos de TypeScript (*.ts).
- La opción outDir especifica la carpeta de salida para los archivos JavaScript sin formato que transpila el compilador de TypeScript.
- La opción sourceMap indica si el compilador genera archivos sourceMap.
La configuración anterior proporciona solo una introducción básica a la configuración de TypeScript. Para obtener información sobre otras opciones, consulte tsconfig.json.

Compilar la aplicación

Agregue archivos TypeScript ( .ts) o TypeScript JSX ( .tsx) al proyecto y, a continuación, agregue código de TypeScript. Para obtener un ejemplo sencillo de TypeScript, use lo siguiente:
```
let message: string = 'Hello World';
console.log(message);
```
Si usa un proyecto anterior de estilo que no es de SDK, siga las instrucciones incluidas en Eliminación de importaciones predeterminadas antes de la compilación.
Elija Compilar > Compilar solución.

Aunque la aplicación se compila automáticamente cuando la ejecuta, queremos fijarnos en algo que ocurre durante el proceso de compilación:

Si ha generado mapas de origen, abra la carpeta especificada en la opción outDir y encontrará los archivos *.js generados junto con los archivos *js.map generados.

Los archivos de asignación de origen son necesarios para la depuración.
Si desea compilar cada vez que guarda el proyecto, use la opción compileOnSave en tsconfig.json.
```
{
   "compileOnSave":  true,
   "compilerOptions": {
   }
}
```

Para ver un ejemplo del uso de gulp con el ejecutor de tareas para compilar la aplicación, consulte ASP.NET Core y TypeScript.

Si experimenta algún problema que provoque que Visual Studio use una versión de Node.js o una herramienta de terceros distinta de la versión esperada, puede que tenga que establecer la ruta de acceso para que Visual Studio la use. Elija Herramientas>Opciones. En Proyectos y soluciones, elija Administración de paquetes web>Herramientas web externas.

Ejecutar la aplicación

Presione F5 o seleccione el botón Iniciar situado en la parte superior de la ventana.

Detalles de la estructura de paquetes NuGet

Microsoft.TypeScript.MSBuild.nupkg contiene dos carpetas principales:

Carpeta build

En esta carpeta hay dos archivos. Ambos son puntos de entrada: para el archivo de destino de TypeScript principal y el archivo de propiedades, respectivamente.
1. Microsoft.TypeScript.MSBuild.targets
  
  Este archivo establece variables que especifican la plataforma en tiempo de ejecución, como una ruta de acceso a TypeScript.Tasks.dll, antes de importar Microsoft.TypeScript.targets desde la carpeta tools.
2. Microsoft.TypeScript.MSBuild.props
  
  Este archivo importa Microsoft.TypeScript.Default.props desde la carpeta tools y establece propiedades que indican que la compilación se ha iniciado a través de NuGet.
Carpeta tools

Las versiones de paquete anteriores a 2.3 solo contienen una carpeta tsc. Microsoft.TypeScript.targets y TypeScript.Tasks.dll se encuentran en el nivel raíz.

En las versiones de paquete 2.3 y posteriores, el nivel raíz contiene Microsoft.TypeScript.targets y Microsoft.TypeScript.Default.props. Para obtener más detalles sobre estos archivos, consulte Configuración de MSBuild.

Además, la carpeta contiene tres subcarpetas:
1. net45
  
  Esta carpeta contiene TypeScript.Tasks.dll y otros archivos DLL de los que depende. Al compilar un proyecto en una plataforma de Windows, MSBuild usa los archivos DLL de esta carpeta.
2. netstandard1.3
  
  Esta carpeta contiene otra versión de TypeScript.Tasks.dll, que se usa al compilar proyectos en una máquina que no es Windows.
3. tsc
  
  Esta carpeta contiene tsc.js, tsserver.js y todos los archivos de dependencia necesarios para su ejecución como scripts de nodo.
  
  Nota:
  
  Si Visual Studio está instalado, el paquete NuGet seleccionará automáticamente la versión de node.exe agrupada con Visual Studio. De lo contrario, deberá instalarse Node.js en el equipo.
  
  Las versiones anteriores a 3.1 contenían un archivo ejecutable tsc.exe para ejecutar la compilación. En la versión 3.1, el archivo ejecutable se quitó en favor del uso de node.exe.

Eliminación de las importaciones predeterminadas

En proyectos de ASP.NET Core anteriores que usan el formato de estilo que no es de SDK, puede que tenga que quitar algunos elementos de archivo del proyecto.

Si se usa el paquete NuGet para la compatibilidad con MSBuild de un proyecto, el archivo del proyecto no debe importar Microsoft.TypeScript.Default.props ni Microsoft.TypeScript.targets. Los archivos los importa el paquete NuGet, por lo que incluirlos por separado podría provocar un comportamiento no intencionado.

Haga clic con el botón derecho en el proyecto y elija Descargar proyecto.
Haga clic con el botón derecho en el proyecto y elija Editar<nombre de archivo del proyecto> .

El archivo del proyecto se abre.

Quite las referencias a Microsoft.TypeScript.Default.props y Microsoft.TypeScript.targets.

Las importaciones que se van a quitar tienen un aspecto similar al siguiente:

<Import
   Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default.props"
   Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.Default.props')" />

<Import
   Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets"
   Condition="Exists('$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\TypeScript\Microsoft.TypeScript.targets')" />

Share via