教程：在 Visual Studio 中将 TypeScript 添加到现有 ASP.NET Core 应用

项目
11/30/2023

在这个使用 ASP.NET Core 和 TypeScript 的 Visual Studio 开发教程中，你将创建一个简单的 Web 应用程序，添加一些 TypeScript 代码，然后运行应用。

从 Visual Studio 2022 及更高版本开始，如需将 Angular 或 Vue 与 ASP.NET Core 配合使用，建议使用 ASP.NET Core 单页应用程序 (SPA) 模板，以通过 TypeScript 创建 ASP.NET Core 应用。有关详细信息，请参阅针对 Angular 或 Vue 的 Visual Studio 教程。

如果尚未安装 Visual Studio，请转到 Visual Studio 下载页免费安装。

在本教程中，你将了解：

创建 ASP.NET Core 项目
添加用于 TypeScript 支持的 NuGet 包
添加一些 TypeScript 代码
运行应用
使用 npm 添加第三方库

先决条件

必须安装 Visual Studio 且具有 ASP.NET Web 开发工作负载。

如果尚未安装 Visual Studio，请转到 Visual Studio 下载页免费安装。
如果需要安装工作负载但已有 Visual Studio，请转到“工具”>“获取工具和功能...”，以打开 Visual Studio 安装程序。选择“ASP.NET 和 web 开发”工作负载，然后选择“修改”。

创建新的 ASP.NET Core MVC 项目

Visual Studio 管理项目中的单个应用程序的文件。该项目包括源代码、资源和配置文件。

注意

要从空的 ASP.NET Core 项目开始并添加 TypeScript 前端，请改为参阅含 TypeScript 的 ASP.NET Core。

在本教程中，将从一个包含 ASP.NET Core MVC 应用代码的简单项目开始。

打开 Visual Studio。如果“开始”窗口未打开，请选择“文件”>“启动窗口”。
在“开始”窗口上，选择“创建新项目”。
在“创建新项目”窗口的搜索框中输入“Web 应用”。接下来，选择“C#”作为语言。

应用语言筛选器后，选择“ASP.NET Core Web 应用程序（模型-视图-控制器）”，然后选择“下一步”。

注意

如果未显示“ASP.NET Core Web 应用程序”项目模板，必须添加“ASP.NET 和 Web 开发”工作负载。有关详细说明，请参阅先决条件。
在“配置新项目”窗口中，在“项目名称”框中输入项目的名称。然后选择下一步。

选择建议的目标框架（.NET 8.0 或长期支持），然后选择“创建”。

在“其他信息”窗口中，确保在“框架”下拉菜单中选择“.NET 8.0”，然后选择“创建”。

此时，Visual Studio 将打开新项目。

添加一些代码

在“解决方案资源管理器”（右侧窗格）中，右键单击项目节点，然后选择“管理解决方案的 NuGet 包”。
在“浏览”选项卡中，搜索 Microsoft.TypeScript.MSBuild。
选择“安装”以安装包。

Visual Studio 会将 NuGet 包添加到解决方案资源管理器中的“依赖项”节点下。
右键单击项目节点，然后选择“添加”>“新建项”。选择“TypeScript JSON 配置文件”，然后选择“添加”。

如果看不到所有项模板，请选择“显示所有模板”，然后选择项模板。

Visual Studio 会将 tsconfig.json 文件添加到项目根目录中。可以使用此文件为 TypeScript 编译器配置选项。
打开 tsconfig.json，将默认代码替换为以下代码：
```
{
  "compileOnSave": true,
  "compilerOptions": {
    "noImplicitAny": false,
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5",
    "outDir": "wwwroot/js"
  },
  "include": [
    "scripts/**/*"
  ]
}
```
outDir 选项会指定 TypeScript 编译器转译的纯 JavaScript 文件的输出文件夹。

此配置提供了使用 TypeScript 的基本简介。在其他方案中，例如在使用 gulp 或 Webpack 时，你可能希望转译的 JavaScript 文件（而不是 wwwroot/js）使用不同的中间位置。位置取决于工具和配置首选项。
在“解决方案资源管理器”中，右键单击项目节点并选择“添加”>“新建文件夹”。为新文件夹使用名称“scripts”。
右键单击“脚本”文件夹，然后选择“添加”>“新建项”。选择“TypeScript 文件”，键入文件名“app.config”，然后选择“添加”。

如果看不到所有项模板，请选择“显示所有模板”，然后选择项模板。

Visual Studio 将 app.config 添加到“scripts”文件夹。

打开 app.config 并添加以下 TypeScript 代码。

function TSButton() {
   let name: string = "Fred";
   document.getElementById("ts-example").innerHTML = greeter(user);
}

class Student {
   fullName: string;
   constructor(public firstName: string, public middleInitial: string, public lastName: string) {
      this.fullName = firstName + " " + middleInitial + " " + lastName;
   }
}

interface Person {
   firstName: string;
   lastName: string;
}

function greeter(person: Person) {
   return "Hello, " + person.firstName + " " + person.lastName;
}

let user = new Student("Fred", "M.", "Smith");

Visual Studio 为 TypeScript 代码提供 IntelliSense 支持。

要尝试此功能，请从 greeter 函数中移除 .lastName，重新输入句点 (.)，并注意 IntelliSense 更新。

View IntelliSense

选择 lastName，将最后一个名称添加回代码。

打开 Views/Home 文件夹，然后打开 Index.cshtml。

在文件末尾添加以下 HTML 代码。

<div id="ts-example">
    <br />
    <button type="button" class="btn btn-primary btn-md" onclick="TSButton()">
        Click Me
    </button>
</div>

打开 Views/Shared 文件夹，然后打开 _Layout.cshtml 。
在调用 @RenderSectionAsync("Scripts", required: false) 前添加以下脚本引用：
```
<script src="~/js/app.js"></script>
```
选择“文件”>“全部保存”（Ctrl + Shift + S）以保存更改。

构建应用程序

选择生成 > 生成解决方案。

尽管应用程序会在运行时自动生成，但我们想要查看在生成过程中发生的一些事情。
打开“wwwroot/js”文件夹以查看两个新文件：app.js 和源映射文件 app.js.map。 TypeScript 编译器将生成这些文件。

调试需要源映射文件。

运行此应用程序

按 F5 （“调试” >“启动调试” ）来运行该应用程序。

应用将在浏览器中打开。

在浏览器窗口中，会看到“欢迎”标题和“单击我”按钮。
选择该按钮可显示在 TypeScript 文件中指定的消息。

调试应用程序

通过在代码编辑器中单击左侧空白，在 app.ts 的 greeter 函数中设置断点。
按 F5 运行该应用程序。

你可能需要回复消息才能启用脚本调试。

注意

客户端脚本调试需要 Chrome 或 Edge。
在页面加载时，按“单击我”。

应用程序在断点处暂停。现在，可以检查变量并使用调试器功能。

为第三方库添加 TypeScript 支持

按照《npm 包管理》中的说明将 package.json 文件添加到项目。此任务会向项目添加 npm 支持。

注意

对于 ASP.NET Core 项目，还可以使用库管理器或 yarn（而非 npm）来安装客户端 JavaScript 和 CSS 文件。
在此示例中，将 jQuery 的 TypeScript 定义文件添加到项目。在 package.json 文件中包括以下代码。
```
"devDependencies": {
  "@types/jquery": "3.5.1"
}
```
此代码会为 jQuery 添加 TypeScript 支持。 MVC 项目模板中已包含 jQuery 库（在解决方案资源管理器中的 wwwroot/lib 下查看）。如果使用其他模板，则可能还需要包含 jquery npm 包。
如果未安装解决方案资源管理器中的包，请右键单击 npm 节点，然后选择“还原包”。

注意

在某些方案中，解决方案资源管理器可能会指示由于此处所述的已知问题，npm 包与 package.json 不同步。例如包在安装后可能会显示为未安装。在大多数情况下，可以通过删除 package.json，重启 Visual Studio 并重新添加 package.json 文件来更新解决方案资源管理器，如本文前面所述。
在解决方案资源管理器中右键单击脚本文件夹，然后选择“添加”>“新项” 。

如果看不到所有项模板，请选择“显示所有模板”，然后选择项模板。
选择“TypeScript 文件”，键入 library.ts，然后选择“添加”。

在 library.ts 中，添加以下代码。

var jqtest = {
  showMsg: function (): void {
     let v: any = jQuery.fn.jquery.toString();
     let content: any = $("#ts-example-2")[0].innerHTML;
     alert(content.toString() + " " + v + "!!");
     $("#ts-example-2")[0].innerHTML = content + " " + v + "!!";
  }
};

jqtest.showMsg();

为简单起见，此代码使用 jQuery 显示消息和警报。

如果添加了 jQuery 的 TypeScript 类型定义，则在 jQuery 对象后面输入句点 (.) 时，可以获得 IntelliSense 对 jQuery 对象的支持，如下所示。

Screenshot that shows Intellisense results for the J Query example.

在 _Layout.cshtml 中，更新脚本引用以包含 library.js。

<script src="~/js/app.js"></script>
<script src="~/js/library.js"></script>

在 Index.cshtml 中，将以下 HTML 添加到文件末尾。

<div>
  <p id="ts-example-2">jQuery version is:</p>
</div>

按 F5 （“调试” >“启动调试” ）来运行该应用程序。

应用将在浏览器中打开。

在警报中选择“确定”，以查看已更新为 jQuery 版本为: 3.3.1!! 的页面。

后续步骤

你可能想要了解有关将 TypeScript 与 ASP.NET Core 结合使用的更多详细信息。如果对 Visual Studio 中的 Angular 编程感兴趣，可使用适用于 Visual Studio 的 Angular 语言服务扩展。

ASP.NET Core 和 TypeScript

Angular 语言服务扩展