Azure Pipelines是微软提供的一个用于代码持续集成以及部署的工具,可以利用它来实现SharePoint Framework代码的持续集成和部署。
目前使用SharePoint Framework开发web part的步骤是:
1,使用Yeoman创建webpart项目
2,代码管理
3,测试
4,打包生成.sppkg文件
5,将.sppkg文件上传到SharePoint App Catalog中
6,在站点页面中添加使用webpart
下面介绍如何使用Azure Pipeline自动化以上步骤,来实现web part开发的持续集成和部署
首先需要有web part项目代码,这里使用的示例代码是我上传到GitHub上的一个项目:https://github.com/shrenky/spfx-ci-demo
然后登陆https://dev.azure.com, 创建一个组织,并在组织中创建一个项目:
创建成功之后,进入这个项目,在左边栏点击“+”,创建一个新的build pipeline,用来自动化代码捆绑,单元测试以及打包:
第一步是选择在哪里获取源代码:
Azure Pipeline支持不同的代码管理工具,因为我的示例代码在GitHub上,所以,以GitHub为例,在这里选择GitHub。
接下来就是连接GitHub,连接成功之后,会列出目前你所有的公共库,这里列出的是我的示例代码spfx-ci-demo:
连接的时候根据提示会安装Microsoft为GitHub开发的Azure Pipelines插件:
接下来选择需要配置持续集成的项目,开始配置,这里选择Node.js环境:
选择之后,Azure Pipeline会默认生成一个yaml文件如下,yaml文件结构请参考这里。
这个yaml配置文件定义了一个pipeline中的job需要执行的任务,其中:
#yaml文件中的#表示注释,下面解释了各个任务的作用
#trigger表示触发条件,这里是在master分支有代码提交的时候触发
trigger:
- master
pool:
vmImage: 'Ubuntu-16.04'
#定义了步骤
steps:
#安装Node.js 8.x版本
- task: NodeTool@0
inputs:
versionSpec: '8.x'
displayName: 'Install Node.js'
#Node.js安装完成之后执行如下命令,npm install用来根据package.json文件中的定义,安装依赖项,然后
#npm run build用来执行代码捆绑
- script: |
npm install
npm run build
displayName: 'npm install and build'
因为默认生成的文件中,指定的Node.js版本是“10.x”,但是目前SharePoint Framework仅支持8.x版本,所以这里将10.x改为8.x:
将node版本从10.x改为8.x,点击“Save and run”按钮:
将代码提交之后,会在web part项目中添加一个“azure-pipelines.yml"的文件,Azure pipeline就是执行这个文件中定义的步骤来实现持续集成。
代码提交后会自动触发一个job,这个job从GitHub中获取你的代码,然后执行yml文件中定义的任务,例如安装nodejs,执行npm install, npm run build等,以下是job成功执行完成之后的页面:
以上就在pipelines中完成了获取代码,配置nodejs环境,安装依赖项,捆绑代码的自动化。下面向项目中配置jest单元测试。
用Code打开web part项目,运行如下命令安装和配置jest。具体步骤参见:
在SharePoint Framework中配置jest进行单元测试
npm install [email protected] @voitanos/jest-preset-spfx --save-dev
npm uninstall @types/jest
npm install @types/[email protected] --save-dev
jest安装完成后,添加测试代码:
然后修改azure-pipelines.yml文件,在捆绑之后自动执行单元测试:
然后添加gulp bundle --ship和gulp package-solution --ship命令,捆绑并且打包web part:
在yml文件中添加CopyFiles任务,将打包生成的.sppkg文件复制到特定文件目录下,其中CopyFiles命令中的参数contents使用通配符匹配文件,参见File matching patterns,这里使用**/*.sppkg匹配打包生成的.sppkg文件,注意这里使用的是‘/’。找到.sppkg文件后,将其复制到$(build.artifactstagingdirectory)这个预定义变量的路径下,关于预定义变量请参见Predefined variables。Overwrite设置为true表示覆盖已有文件。
复制文件结束后,添加PublishBuildArtifacts命令如下。
以上就完成了web part代码从获取代码到生成.sppkg包的自动化,提交以上对yml文件的修改,自动触发pipeline job,成功之后,就可以配置自动部署了。自动部署就是将.sppkg包上传到SharePoint App Catalog中。
首先创建一个release pipeline:
在选择模板的时候,选择Empty job:
添加一个artifact:
指定一个Source alias,可以随意指定。
这里可以添加task是可视化的UI,可以在搜索框里搜索预定义好的任务,首先是安装Node.js
添加之后,需要将版本改为8.x:
然后安装office 365 cli,这是一个命令行工具,可以将.sppkg包上传到SharePoint App Catalog中,配置如下:
添加一个Command Line命令行任务,使用office 365 cli连接SharePoint Online,其中使用了一些变量例如$(tenant), $(username)等,这些需要稍后手动配置。这里有一个需要注意的地方, 如果从来没有使用office 365 cli登陆过,需要在本地安装office 365 cli,先连接一次SharePoint Onlie,否则后面运行job的时候,会报错(具体错误参见博客最后部分)
具体连接命令:
o365 spo login https://$(tenant).sharepoint.com/$(catalogsite) --authType password --userName $(username) --password $(password)
再添加一个Command Line任务,将.sppkg包上传到App Catalog中去,这里需要在预定义的$(System.DefaultWorkingDirectory)之后指定一个路径:
o365 spo app add -p $(System.DefaultWorkingDirectory)/CIDemoSPPKG/CIDemoSPPKG/sharepoint/solution/spfx-ci-demo.sppkg --overwrite
这里的路径是这样获取的:
点击“Advanced”显示Working Directory,然后点击"..."按钮选择文件
弹出框里选择sppkg包:
把这个路径copy出来,填写到script中去。
部署.sppkg包:
o365 spo app deploy --name spfx-ci-demo.sppkg --appCatalogUrl https://$(tenant).sharepoint.com/$(catalogsite)
以上就配置完成release pipeline了,最后设置配置过程中使用到的变量,打开”Variables" 选项卡,添加如下变量,其中:
tenant是租户domain,例如你的SharePoint Online url为:https://contoso.sharepoint.com,那么tenant就是contoso
catalogsite是App Catalog站点的相对路径,每个租户都一样是sites/appcatalog
用户名和密码是登陆SharePoint Online的用户密码,这里使用的是SharePoint管理员
最后保存:
设置触发器:
以上就是持续部署的配置,修改web part,提交代码,就会自动触发持续集成和部署,将.sppkg文件部署到App Catalog中去:
配置过程中可能遇到的错误:
在CopyFiles任务中,显示”found 0 files“,需要修改CopyFiles的contents参数为'**/*.sppkg'(微软的文档中是反斜线,导致找不到文件):
Error: AADSTS65001: The user or administrator has not consented to use the application with ID '31359c7f-bd7e-475c-86db-fdb8c937548e' named 'PnP Office 365 Management Shell'. Send an interactive authorization request for this user and resource.
这里需要在本地安装office 365,手动连接spo一次。
在添加sppkg包到App Catalog中的时候找不到文件:
这个是script中提供的路径不对,获取路径的方法展开”Advanced“ ,在Working Directory中选择文件,然后把路径copy出来使用即可:
参考:
https://azure.microsoft.com/en-us/services/devops/pipelines/?nav=min
https://github.com/VelinGeorgiev/DevOps
https://segmentfault.com/a/1190000016526361
https://docs.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/implement-ci-cd-with-azure-devops
http://thecollaborationcorner.com/2019/02/28/azure-devops-with-spfx-gitflow-gitversion/
https://github.com/SharePoint/sp-dev-build-extensions/tree/master/samples/azure-devops-ci-cd-spfx