文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载本篇技术指南以本仓库《TypeScript 使用手册中文版》的 ASP.NET Core 教程 为骨架完整演示如何在 Visual Studio2015 / 2017中新建 ASP.NET Core 空工程、配置静态文件中间件、接入 TypeScript 编译管线tsconfig.json NPM Gulp并最终将工程升级为包含 Angular 2 组件、SystemJS 模块加载的完整示例。读完本文你将掌握ASP.NET Core TypeScript Gulp这一经典开发链路的每一步配置细节并理解noImplicitAny、compileOnSave、experimentalDecorators等关键编译器选项的真实作用。需要说明的是本教程对应的 ASP.NET Core 版本为 1.x 时代的工具链Visual Studio 2015 / 2017、project.json/ RC1 包、Angular 2 beta其中的静态文件中间件、tsconfig.json编译配置、Gulp 构建流水线等核心思路在现代项目中依然成立但具体包名、版本号与目录结构请以你所使用的新版本工具为准。环境准备安装 ASP.NET Core 与 TypeScript在开始之前需要确认本机的开发环境满足以下条件安装 ASP.NET Core本教程需要 Visual Studio 2015 或 2017并配套安装 ASP.NET Core 开发负载。若尚未安装请通过 Visual Studio 安装程序选择对应工作负载完成安装。安装 TypeScript 插件如果你的 Visual Studio 未内置最新版本的 TypeScript需要单独安装 TypeScript 的 VS 扩展支持 VS2015 / VS2017 的 TypeScript 官方扩展安装完成后 TypeScript 会以新建项New Item模板的形式出现在工程中。版本适配提示本教程撰写于 ASP.NET Core 1.0 / 1.1RC1 至正式版时期VS2015 侧使用project.json描述依赖VS2017 侧使用.csproj NuGet 包引用。新版本 Visual Studio 已使用基于 SDK 的.csproj工程格式操作入口可能不同但下述新建空工程 → 配置静态文件 → 接入 TypeScript 编译的流程逻辑完全可复用。新建工程从空模板起步本教程刻意选用空模板Empty Template这样可以把注意力集中在 TypeScript 与构建链路的配置上而不是被 MVC 模板的默认代码干扰。操作步骤VS2015 / VS2017 通用入口选择File文件菜单选择New Project快捷键 Ctrl Shift N在模板树中选择Visual C#若使用 VS2015选择ASP.NET Web Application再选ASP.NET 5 Empty模板并取消勾选 Host in the cloud——因为我们将在本地运行调试若使用 VS2017选择ASP.NET Core Web Application (.NET Core)再选ASP.NET Core 1.1 Empty模板。工程创建完成后先直接运行一次应用确认默认的空站点能够正常启动这一步可以提前暴露端口占用、IIS Express 配置等环境问题。设置服务项让 ASP.NET Core 能提供静态文件空模板默认不会注册静态文件中间件因此浏览器无法直接访问wwwroot下的index.html与 JS 文件。我们需要按 VS 版本分别配置。VS2015修改 project.json 与 Startup.csVS2015 的 ASP.NET 5 工程使用project.json描述依赖。在dependencies字段中新增静态文件包Microsoft.AspNet.StaticFiles: 1.0.0-rc1-final添加后完整的dependencies部分应类似如下dependencies: { Microsoft.AspNet.IISPlatformHandler: 1.0.0-rc1-final, Microsoft.AspNet.Server.Kestrel: 1.0.0-rc1-final, Microsoft.AspNet.StaticFiles: 1.0.0-rc1-final },然后用下面的代码替换Startup.cs中的Configure方法public void Configure(IApplicationBuilder app) { app.UseIISPlatformHandler(); app.UseDefaultFiles(); // 将默认文档如 index.html映射为根路径响应 app.UseStaticFiles(); // 提供 wwwroot 下静态文件的访问能力 }其中UseIISPlatformHandler()是 IIS 宿主环境处理管线所必需VS2015 时代的标准样板代码UseDefaultFiles()允许访问站点根路径时自动返回wwwroot/index.htmlUseStaticFiles()则负责将wwwroot目录暴露为静态资源根目录——这三个中间件的注册顺序即代表了 ASP.NET Core 中间件管线的执行顺序。VS2017通过 NuGet 安装静态文件包VS2017 使用 NuGet 包引用体系。操作路径为Dependencies依赖项→Manage NuGet Packages管理 NuGet 包→Browse浏览搜索并安装Microsoft.AspNetCore.StaticFiles1.1.2安装完成后将Startup.cs的Configure方法替换为如下内容VS2017 不再需要UseIISPlatformHandler它已被 WebHost 自动集成public void Configure(IApplicationBuilder app) { app.UseDefaultFiles(); app.UseStaticFiles(); }修改后如果UseDefaultFiles与UseStaticFiles下方出现红色波浪线通常是因为 NuGet 还原尚未完成或 IntelliSense 缓存过期重启 Visual Studio即可消除。添加 TypeScript创建源文件与示例代码接下来建立 TypeScript 源码目录在解决方案资源管理器中右键工程 →Add→New Folder创建新文件夹将文件夹命名为scripts它对应本仓库 ASP.NET 4 教程中的src目录命名本身不影响构建只要与后续tsconfig.json、Gulp 路径配置保持一致即可在scripts文件夹上右键 →Add→New Item选择TypeScript File模板VS2017 中该模板位于 .NET Core 分组下将文件命名为app.ts向app.ts写入如下示例代码——它读取两个输入框的值并拼接出一句问候语function sayHello() { const compiler (document.getElementById(compiler) as HTMLInputElement) .value; const framework (document.getElementById(framework) as HTMLInputElement) .value; return Hello from ${compiler} and ${framework}!; }注意这里的as HTMLInputElement类型断言getElementById返回的是HTMLElement通过断言收窄为HTMLInputElement后才能安全访问.value属性。这正是 TypeScript 在 DOM 操作中发挥类型保护作用的典型场景。构建设置tsconfig.json NPM Gulp 三件套本教程的构建链路是TypeScript 编译器负责类型检查与转译NPM 负责拉取构建依赖Gulp 负责把编译产物搬运到wwwroot。三个配置文件缺一不可。配置 TypeScript 编译器tsconfig.json右键scripts文件夹 →Add→New Item选择TypeScript Configuration File模板保持默认文件名tsconfig.json将默认内容替换为{ compilerOptions: { noImplicitAny: true, // 表达式或声明中隐式 any 时报错 noEmitOnError: true, // 存在编译错误时不生成输出文件 sourceMap: true, // 生成 .map 文件支撑浏览器源码级调试 target: es5 // 编译目标为 ES5兼容旧浏览器 }, files: [ // 显式列出待编译文件而非依赖目录扫描 ./app.ts ], compileOnSave: true // 保存文件时由 IDE 自动编译 }与默认模板相比关键差异有三处逐一说明noImplicitAny: true从编译选项文档可知该选项的作用是在表达式和声明上有隐含的any类型时报错。在编写新代码时开启它是个好习惯——任何因漏写类型注解而产生的隐式any都会立刻被编译器指出从源头上避免类型退化为any。显式列出files而非依赖exclude排除files是编译入口的显式白名单app.ts中被import引用的其它文件会被自动纳入编译。若使用include/exclude的 glob 写法如exclude: [node_modules]目录中任何满足模式的文件都会被编译进来控制粒度不如files明确。两种方式的完整语义参见仓库的 tsconfig.json 详解。compileOnSave: true这是tsconfig.json的顶层选项与compilerOptions平级让 IDE 在保存文件时依据配置自动重新编译。该特性需要 Visual Studio 2015 及 TypeScript 1.8.4 以上版本支持本教程的 VS2017 天然满足。配合noEmitOnError: true一旦写坏代码保存后立即报错且不会生成脏的 JS 输出等于把编译 → 反馈循环压缩到每次保存。另外sourceMap: true会为每个输出 JS 生成对应的.map文件这是后续在 Edge 调试器里直接对app.ts源码打断点的前提。target: es5把 ES2015 语法如模板字符串降级为 ES5保证旧版浏览器可运行。配置 NPMpackage.json为了让工程具备使用 JavaScript 包的能力右键工程 →Add→New Item选择NPM Configuration File模板保持默认文件名package.json在devDependencies部分加入gulp与deldevDependencies: { gulp: 3.9.0, // 任务化构建工具 del: 2.2.0 // 删除文件供 clean 任务使用 }保存文件后Visual Studio 会基于该文件自动执行包还原Restore开始安装 gulp 与 del。若没有自动开始右键package.json选择Restore Packages手动触发。设置 Gulpgulpfile.js最后在工程根目录添加一个 JavaScript 文件gulpfile.js键入以下内容/// binding AfterBuilddefault Cleanclean / /* This file is the main entry point for defining Gulp tasks and using Gulp plugins. Click here to learn more. http://go.microsoft.com/fwlink/?LinkId518007 */ var gulp require(gulp); var del require(del); var paths { scripts: [scripts/**/*.js, scripts/**/*.ts, scripts/**/*.map], }; gulp.task(clean, function () { return del([wwwroot/scripts/**/*]); }); gulp.task(default, function () { gulp.src(paths.scripts).pipe(gulp.dest(wwwroot/scripts)); });这段文件包含两层信息文件首行的/// binding AfterBuilddefault Cleanclean /是 Visual Studio 的 Gulp 绑定指令AfterBuilddefault告诉 VS 在每次构建完成后自动运行default任务Cleanclean则声明当执行清理解决方案时调用clean任务。这是 VS 内建任务运行器与 Gulp 衔接的约定。任务逻辑本身default任务把scripts目录下的.js编译产物、.ts源码便于出错排查、.mapsource map全部拷贝到wwwroot/scriptsclean任务则清空wwwroot/scripts目录。值得强调的是这里 Gulp 只负责搬运编译产物真正的 TypeScript → JavaScript 转译由compileOnSave触发的 tsc 完成。如果你更倾向用 Gulp 直接驱动编译而非依赖 IDE 保存触发可以参考本仓库的 Gulp 教程——它演示了使用gulp-typescript插件通过tsProject.src().pipe(tsProject()).js.pipe(gulp.dest(dist))在管道内完成编译的替代方案两者解决的构建问题不同可按团队习惯选择。保存后右键gulpfile.js选择Task Runner Explorer任务运行程序资源管理器。若default与clean任务未显示请点击 explorer 的刷新按钮编写 HTML 页在wwwroot下添加新建项index.html写入如下代码!DOCTYPE html html head meta charsetutf-8 / script srcscripts/app.js/script title/title /head body div idmessage/div div Compiler: input idcompiler valueTypeScript onkeyupdocument.getElementById(message).innerText sayHello() /br / Framework: input idframework valueASP.NET onkeyupdocument.getElementById(message).innerText sayHello() / /div /body /html页面结构说明script srcscripts/app.js/script引用的是wwwroot/scripts/app.js——即由app.ts编译、再经 Gulp 搬运后的 JS 文件注意引用的是.js而非.ts因为浏览器只能执行 JS两个输入框的onkeyup事件直接调用全局函数sayHello()把返回的问候语写入#message元素输入框初始值分别设为TypeScript与ASP.NET页面一加载即可看到Hello from TypeScript and ASP.NET!。测试运行运行项目F5在两个输入框中键入文字页面会实时显示拼接出的消息若能正常看到Hello from ...的实时更新说明TypeScript 编译 → Gulp 搬运 → 静态文件中间件 → 浏览器执行整条链路已经打通。调试在浏览器中直接打断点得益于sourceMap: true我们可以在浏览器调试器中直接对 TypeScript 源码进行断点调试而不是在转译后的 JS 里猜行号在 Edge 浏览器中按F12打开开发者工具选择Debugger调试程序标签页展开 localhost 列表选择scripts/app.tssource map 让调试器能定位到 .ts 源码在return那一行上打一个断点在页面输入框中键入内容确认 TypeScript 代码命中断点并单步观察变量值是否正确这就是在 ASP.NET 中运用 TypeScript 的基础能力。接下来进入进阶环节引入 Angular 2把它接入现有构建管线。进阶添加 Angular 2Angular 2 是一套完整的客户端框架接入工程需要同时处理好依赖包、编译器选项、构建任务与页面加载方式四个方面。第一步用 NPM 下载依赖包把 Angular 2 与 SystemJS模块加载器加入package.json的dependencies注意是运行时依赖而不是devDependencies。VS2015 版本的依赖列表如下dependencies: { angular2: 2.0.0-beta.11, systemjs: 0.19.24, gulp: 3.9.0, del: 2.2.0 },VS2017 版本需要额外处理 NPM 3 对 peer dependencies同行依赖的策略变化NPM3 默认不再自动安装被依赖包声明为同行依赖的包因此必须把 Angular 2 的同行依赖显式列为直接依赖dependencies: { angular2: 2.0.0-beta.11, reflect-metadata: 0.1.2, rxjs: 5.0.0-beta.2, zone.js: ^0.6.4, systemjs: 0.19.24, gulp: 3.9.0, del: 2.2.0 },其中reflect-metadata是装饰器元数据反射的实现rxjs是 Angular 2 响应式编程的依赖zone.js负责变更检测与脏检查——这些正是 NPM3 下需要手工补齐的同行依赖。保存文件后VS 会自动还原这些包。第二步更新 tsconfig.json 以支持装饰器与 ES2015 声明Angular 2 重度依赖 TypeScript 的**装饰器Decorator**语法。装饰器目前仍属于实验性特性在 TypeScript 中需显式开启因此在compilerOptions中补充experimentalDecorators: true启用实验性的 ES 装饰器emitDecoratorMetadata: true为源码中的装饰器声明生成设计时类型元数据如design:type、design:paramtypesAngular 2 的依赖注入依赖这些元数据来推断注入类型。这两项选项的具体语义可参见编译选项文档与仓库的 Decorators 专题。同时Angular 使用 core-js 来提供Promise等 ES2015 能力所以还需要通过lib引入 ES2015 的声明文件lib: [ es2015, es5, dom ]lib控制编译过程中需要引入的库文件列表手动指定后编译器不再依据target推断默认库因此必须把es5、dom一并列出否则连基础 DOM 类型都会缺失。最后把即将创建的./model.ts加入files。更新后的完整tsconfig.json{ compilerOptions: { noImplicitAny: true, noEmitOnError: true, sourceMap: true, experimentalDecorators: true, emitDecoratorMetadata: true, target: es5, lib: [ es2015, es5, dom ] }, files: [ ./app.ts, ./model.ts, ./main.ts, ], compileOnSave: true }说明原教程预计未来的版本中装饰器会成为默认设置——这一预期在 TypeScript 5.x 之后部分成真新提案装饰器在部分配置下默认可用但emitDecoratorMetadata等旧式装饰器语义仍由编译器选项控制。以当前仓库的编译选项文档为准这两项始终标注为实验性[1]。第三步把 Angular 库文件纳入 Gulp 构建Angular 2 的运行时文件位于node_modules中浏览器无法直接引用该目录因此需要把运行所需的库文件复制进wwwroot。修改gulpfile.js完成三件事声明库文件目录、新增lib任务、把lib设为default的前置依赖。/// binding AfterBuilddefault Cleanclean / /* This file is the main entry point for defining Gulp tasks and using Gulp plugins. Click here to learn more. http://go.microsoft.com/fwlink/?LinkId518007 */ var gulp require(gulp); var del require(del); var paths { scripts: [scripts/**/*.js, scripts/**/*.ts, scripts/**/*.map], libs: [node_modules/angular2/bundles/angular2.js, node_modules/angular2/bundles/angular2-polyfills.js, node_modules/systemjs/dist/system.src.js, node_modules/rxjs/bundles/Rx.js] }; gulp.task(lib, function () { gulp.src(paths.libs).pipe(gulp.dest(wwwroot/scripts/lib)); }); gulp.task(clean, function () { return del([wwwroot/scripts/**/*]); }); gulp.task(default, [lib], function () { gulp.src(paths.scripts).pipe(gulp.dest(wwwroot/scripts)); });改动要点paths.libs精确列出 4 个运行时文件Angular 2 本体、其 polyfills、SystemJS 加载器、RxJSlib任务把它们统一输出到wwwroot/scripts/lib供 HTML 直接引用default任务的依赖数组[lib]保证库文件在业务脚本之前就位。保存 gulpfile 后刷新Task Runner Explorer确认lib任务已出现在任务列表中。第四步用 TypeScript 编写一个简单的 Angular 应用将app.ts改写为 Angular 2 组件——注意Component装饰器的使用这正是上一步开启experimentalDecorators的意义所在import { Component } from angular2/core; import { MyModel } from ./model; Component({ selector: my-app, template: divHello from {{ getCompiler() }}/div, }) export class MyApp { model new MyModel(); getCompiler() { return this.model.compiler; } }接着在scripts中添加数据模型文件model.tsexport class MyModel { compiler TypeScript; }再添加引导入口main.ts负责启动组件import { bootstrap } from angular2/platform/browser; import { MyApp } from ./app; bootstrap(MyApp);第五步更新 index.html用 SystemJS 加载应用最后把wwwroot/index.html改为通过 SystemJS 按需加载模块!DOCTYPE html html head meta charsetutf-8 / script srcscripts/lib/angular2-polyfills.js/script script srcscripts/lib/system.src.js/script script srcscripts/lib/rx.js/script script srcscripts/lib/angular2.js/script script System.config({ packages: { scripts: { format: cjs, defaultExtension: js } } }); System.import(scripts/main).then(null, console.error.bind(console)); /script title/title /head body my-appLoading.../my-app /body /html页面加载逻辑拆解依次加载 Angular polyfills、SystemJS、RxJS 与 Angular 2 本体——这些正是 Gulplib任务搬运到wwwroot/scripts/lib的文件System.config声明scripts目录下的模块采用CommonJS 格式format: cjs、默认扩展名为js。由于 TypeScript 默认按 CommonJS 输出模块SystemJS 才能正确解析main.js中require风格的模块声明System.import(scripts/main)异步加载并执行入口模块最终把my-app组件渲染到页面加载失败的错误会被console.error打印到控制台便于排查body内的my-appLoading.../my-app是组件的挂载点Angular 引导完成后会被组件模板替换。至此运行 ASP.NET 应用你应该能看到一个显示 Loading... 的 div 在应用加载完成后更新为 Hello from TypeScript——Angular 2 已经成功在 ASP.NET Core 托管的静态资源之上运行起来了。总结与延伸阅读整个示例的演进路径可以概括为两条主线服务端空模板 → 静态文件中间件UseDefaultFilesUseStaticFiles→wwwroot成为可访问的静态站点根前端构建app.tsTypeScript 源码→tsconfig.json编译规则 compileOnSave→ Gulp 搬运到wwwroot/scripts→ 浏览器通过script或 SystemJS 加载执行。其中每一次配置都对应一个可独立验证的环节静态文件服务通了页面才能访问source map 开了调试器才能定位 .ts装饰器选项开了Angular 组件才能被正确解析——这正是文档教你配置、配置决定行为的完整闭环。本教程与仓库中其它文档的配合阅读建议想深入理解files/include/exclude/extends/compileOnSave等全部顶层语义参见 tsconfig.json 详解想查阅全部编译选项的类型、默认值与作用参见 编译选项参考想了解用 Gulp 直接驱动编译、以及 Browserify / Uglify / Babel 等进阶管线参见 Gulp 教程想系统掌握装饰器的组合顺序、工厂与求值规则参见 Decorators 专题本教程的姊妹篇 ASP.NET Core 教程本文所基于的原文档与 ASP.NET 4 教程 使用了wwwroot与Scripts/App两种不同的输出目录组织方式对照阅读可以加深对编译输出目录这一变量的理解若还不太熟悉 TypeScript 基本语法建议先阅读 5 分钟了解 TypeScript。最后再次提醒教程中的版本号ASP.NET Core RC1/1.1、Angular 2 beta、Gulp 3.9属于历史工具链快照在当今工程中请以对应框架的最新稳定版本文档为准但空模板起步 → 静态文件中间件 → tsconfig 编译配置 → 任务化构建 → 模块化前端框架集成这条从零到一的技术路径至今仍是值得复用的工程范式。赞分享文档教程【免费下载链接】TypeScriptTypeScript 使用手册中文版翻译。http://www.typescriptlang.org项目地址https://gitcode.com/gh_mirrors/typ/TypeScript点击查看免费下载相关推荐TypeScript 与 ASP.NET 4 集成实战从 tsconfig 编译配置到 Angular 2 示例TypeScript 与 ASP.NET 4 集成实战从 tsconfig 编译配置到 Angular 2 示例 本文面向在 ASP.NET 4MVC 5文档教程基于 ASP.NET Boilerplate 构建多租户 SaaS 应用EventCloud 实战ASP.NET Core EF Core Angular 5基于 ASP.NET Boilerplate 构建多租户 SaaS 应用EventCloud 实战ASP.NET Core EF Core Angu后端Web框架依赖注入认证鉴权h3 静态资源服务实战用 serveStatic 搭建高性能静态文件服务器h3 静态资源服务实战用 serveStatic 搭建高性能静态文件服务器 本文基于 h3 仓库中 serve static assets 示例文档 http后端Web框架上一篇WPF UI 入门指南从零开始构建 Fluent 风格 WPF 应用下一篇Jellyfin 歌单同步到映射目录基于硬链接的 Python 同步脚本实战xiaomusic 歌单对接创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考