SharePoint Framework系列(五)-SharePointFramework Toolchain

概述

SharePoint Framework  Toolchain包含了一系列的打包工具，Framework包，以及管理打包和部署client side工程的管理工具。Toolchain用于帮助你构建client-side的组件，例如web part，同样也能帮助你在本地部署环境中使用工具（Workbench）测试web part，你可以使用Toolchain打包工程并且部署到SharePoint环境中。Toolchain提供了一系列的build命令用于帮助你完成关键的打包步骤，例如：编译代码，包装client-side工程到SharePoint app包中。

npm

在讲解toolchain各个组件之前，非常有必要了解一下SharePoint Framework是如何在工程中使用 npm的管理不同的module的，npm是一个首选的用于JavaScript client-side 开发的开源打包管理工具。

一个典型的npm包包含了一个或者多个叫做module的，可以重用的JavaScript文件，并且包含他们的依赖文件，当你安装package,npm同时会安装他们的依赖文件。官方的 npm registry网站包含了几百个package包，你可以下载这些包构建你想要的程序。你同样也可以 发布自己的package到npm 共享给其他的开发人员。SharePoint Framework不仅在toolchain中使用了一些其它package，同时也发布了 自己的package到 npm resigtry。

SharePoint Framework packages

SharePoint Framework包含了一系列可以帮助开发者构建client-side 工程的 npm package。以下是SharePoint Framework中的package

1. @microsoft/generator-sharepoint ： 一个 Sharepoint Framework的Yeoman 插件，使用这个插件开发者可以快速创建带有code模板和最佳实践的client-side webpart工程

2. @microsoft/sp-client-base ：定义了用于开发client-side应用程序的核心库。

3. @microsoft/sp-client-preview ：包含了一系列正处于开发阶段的组件，一旦测试完成这些组件会放在不同的package中。

4. @microsoft/sp-webpart-workbench ：SharePoint Workbench是一个独立的用于测试和调试client-side web part的环境。

5. @microsoft/sp-module-loader ：一个模块加载器用于管理版本和加载client-side 组件，webparts和其它的一些资源，也提供了一些基础的诊断服务。他是构建在比较熟悉的标准之上的，例如：SystemJS和WebPack。它是页面加载时SharePoint Framework中第一个被加载的部分。

6. @microsoft/sp-module-interfaces ：定义了一系列的接口，这些接口被SharePoint Framework module loader和打包系统使用。

7. @microsoft/sp-lodash-subset：一个被SharePoint Framework module loader使用的lodash的定制包。为了提高效率，只包含了一些基本的lodash函数。

8. @microsoft/sp-tslint-rules ：定义了SharePoint client-side工程的tslint 规则用法。

9. @microsoft/office-ui-react-bundle ：SharePoint Framework module loaders使用到的最佳的office-ui-fabric-react的定制包。

Common build tools packages

除了上面的SharePoint Framework package，一些通用的构建工具也是必要的，例如：把TypeScript代码编译成JavaScript，把SCSS转换成CSS。以下是SharePoint Framework中用到的通用的构建工具包：

1. @microsoft/sp-build-core-tasks：SharePoint Framework打包系统的一系列任务，构建在gulp之上的，这个package实现了操作SharePoint的具体方法，例如：打包solution和修改mainfests。

2. @microsoft/sp-build-web：导入并且配置一系列打包任务。

3. @microsoft/gulp-core-build：核心的gulp打包任务，主要用于打包TypeScript，Html，Less和其他的一些文件。这个package依赖于如下的package

   • @microsoft/gulp-core-build-typescript
   • @microsoft/gulp-core-build-sass
   • @microsoft/gulp-core-build-webpack
   • @microsoft/gulp-core-build-serve
   • @microsoft/gulp-core-build-karma
   • @microsoft/gulp-core-build-mocha

4. @microsoft/loader-cased-file：webpack file-loader的包装，主要用于修改 所生成的文件。在某些情况下非常有用，例如：在使用CDN的时候只允许小写的文件名。

5. @microsoft/loader-load-themed-styles：一个加载器，主要用于在Script中加载css，等同于require('load-themed-styles').loadStyles(/* css text */)..

6. @microsoft/loader-raw-script ：在webpack bundle中直接加载Script文件内容的加载器。

7. @microsoft/loader-set-webpack-public-path：用于把参数列表中的值设置到webpack_public_path 变量的加载器。

client-side project结构

SharePoint generator生成了一个包含web part的client-side project ，generator也会为指定的client-side project下载和配置必要的toolchain组件。

Packages installation

generator安装必要的package到本地的工程目录下面，npm允许你安装package到本地工程中或者全局工程中，两者都有一定的有点，但是如果你的code依赖于其他的package  通用做法是安装到本地。例如在web part工程中，你的web part code依赖于各种各样的SharePoint和Common的打包package，因此需要这些package安装到本地。

因为这些package安装到了本地，npm同样会安装这些package依赖的package。你可以在你的工程目录下面的node_modules文件夹下面查看已经安装的package。这个folder包含了package以及他们的依赖package。理想情况下是这个folder下包含几十到几百个npm package的文件夹，然后在这些文件夹下面在包含几十到几百个已经安装的package.SharePoint Framework的关键folder是node_modules\@microsoft 文件夹。@microsoft是一个npm范围，主要代表微软发布的package。

每次你使用generator创建一个新的project，generator都会安装SharePoint Framework package以及他们的依赖package到本地，在这种方式下，npm能保证很容易管理你的web part工程而不会影响到其它本地环境中的project。

package.json

在client-side工程下面的package.json指定了当前工程依赖的package。这个列表中列出了哪些依赖要安装。像前面的描述那样，每个依赖都可能包含多个，npm允许你通过dependencies和devDependencies属性定义运行时和编译时的依赖。devDependencies属性用于你在build web part的时候使用的module。下面是helloword-wepart的package.json文件

{
  "name": "helloword-webpart",
  "version": "0.0.1",
  "private": true,
  "engines": {
    "node": ">=0.10.0"
  },
  "dependencies": {
    "@microsoft/sp-client-base": "~0.1.12",
    "@microsoft/sp-client-preview": "~0.1.12"
  },
  "devDependencies": {
    "@microsoft/sp-build-web": "~0.4.32",
    "@microsoft/sp-module-interfaces": "~0.1.8",
    "@microsoft/sp-webpart-workbench": "~0.1.12",
    "gulp": "~3.9.1"
  },
  "scripts": {
    "build": "gulp bundle",
    "clean": "gulp nuke",
    "test": "gulp test"
  }
}

这些项目中安装的多个package只有在开发环境中构建web part的时候才是必须的，使用这些package你可以使用这些module，打包编译和部署你的webpart。最终你部署到CDN和SharePoint中的web part实际上不会包含这些package。也就是说，你同样可以根据你的需求配置一些指定的modules。更多信息请参见 添加额外的library到web part上面。

使用代码管理工具(例如：svn)

随着项目的依赖越来越多，需要安装的package也会越来越多。你可能不想提交node_modules文件夹到你的代码管理系统中，因为这个folder包含了很多的依赖package。你可以在提交的时候去掉node_modules文件夹。

如果你使用git作为代码管理工具，在工程目录下面有一个.gitignore的文件，这个文件 会忽略node_modules文件夹，当你第一次从代码管理系统中迁出或者克隆项目文件的时候，你需要运行如下命令在本地帮你安装这些依赖

npm i

npm会查找package.json文件中指定的依赖，从而帮你安装对应的依赖package。

Build Task

• SharePoint Framework使用gulp执行如下的打包步骤
• 合并压缩JavaScript和CSS文件。
• 在每次打包前运行tool调用捆绑和压缩的任务。
• 编译LESS和SASS成CSS。
• 编译TypeScript文件成JavaScript。

ToolChain在@microsoft/sp-build-core-tasks包中包含了如下的gulp任务：

• build：打包client-side solution 工程。
• bundle：合并client-side 的入口点以及所有依赖到一个单独的JavaScript文件中。
• serve：在本地环境中为client-side solution工程提供运行服务，既：启动node.js为工程提供IIS服务。
• nuke：清理工程目录下面的lib和dist文件中，之前打包生成的文件。
• test：运行单元测试。
• package-solution：把client-side 工程打包成SharePoint 安装包(spapp文件)。
• deploy-azure-storage：部署client-side工程中的关联文件(css,js和image等)到CDN。

要调用上面不同的task，只需要在gulp后面输入上面的命令就行，例如：要在SharePoint Workbench上面编译然后预览你的web part，只需要云心如下命令即可：

gulp serve

注意: 在同一个时刻不能同时运行多个命令

serve会运行不同的task，之后加载SharePoint Workbench。如下图：

Build Targets

在上图中你可以看到，任务支出你的编译方式如下：

Build target: DEBUG

如果没有指定参数，命令会使用BUILD模式作为目标，如果使用ship作为参数，命令会使用SHIP模式作为目标。对于测试和调试的场景你需要使用BUILD的模式作为目标，使用SHIP模式能打包简化版本的web part。

如果要使用SHIP模式，请使用如下命令：

gulp --ship

在Debug模式，打包任务会复制所有的web part的资源到dist文件夹。

在SHIP模式下，打包任务会复制所有的web part的资源到temp\deploy文件夹下面。

注意：SharePoint Framework目前正处于Preview阶段，随时会进行一些更改。SharePoint Framework Client-side web parts在Office 365的生产环境中暂时不支持。