Avoiding dependency issues in SharePoint Framework (SPFx) 开发者elopment

我在我谈论的一个领域“使用SharePoint框架进行开发时避免陷阱”谈话是依赖关系，是您可能遇到的问题。是否依赖jQuery，Angular，React或其他JS库取决于您，但是总会有一些– and npm 通常是将这些库引入SPFx解决方案的方法。使用基于TypeScript / JavaScript的代码堆栈和npm包与.NET完全不同，我认为大多数SharePoint开发人员对于这个世界来说都是相当陌生的。那里’使用npm本身需要学习很多东西，但这对于使用SPFx成功进行团队开发非常重要。当然，如果您对npm，gulp和node.js感兴趣，’我已经做了很多现代的，以JS为中心的Web开发（我不这样做）’并不是jQuery！），但是除了编码方面，这里还有更深层次的话题。

To get the 开发者elopment and ALM process right with SPFx, some of the answers lie in use of commands like npm收缩包装，对package.json文件以及开发人员如何指定不同类型的依赖关系有深入的了解。但是在详细介绍之前，让’首先从讨论问题和了解一些一般背景开始。

我使用下面的幻灯片总结了该领域的一些关键陷阱，将它们分为“dev” and “shipping” considerations:

What are caret 依存关系 (never mind why they can be a pitfall)? What does –save 做的 npm安装 命令？如果这些是你的问题’现在问，然后是我的同伴帖子 SPFx-node_modules，package.json和其他节点概念的概述 可能会有用。

否则，让’s get to the detail.

没有在npm install上指定--save

对于不太熟悉npm的团队/开发人员来说，这是一个新手陷阱。当开发人员通过npm install添加软件包时，该软件包将从npm存储库下载并安装到您的应用程序中–至少在运行该命令的计算机和文件夹中。添加--save标志可确保该依赖项也记录在package.json中–此后，当任何开发人员为此应用程序运行npm install或npm update时，npm将再次确保适当的程序包已在本地下载并安装（因为package.json文件是通过源代码控制共享的）。它’与仅添加本地文件引用相比，相当于通过NuGet添加.NET依赖项。与以往一样，将整套软件包本身检查到源代码控制中通常不是一个好主意。 因此，陷阱很简单-如果开发人员在安装软件包时忘记使用--save标志，则package.json中不会出现任何条目，并且由于其他计算机上缺少库可能会导致代码失败。 您’会看到TypeScript编译错误，例如“Cannot find module”当另一个开发人员尝试构建或运行代码时（例如 喝一口）：

建议–始终通过指定--save参数（或以下选项之一，例如–保存精确）在运行npm install时。

您还可以在这里为您的团队考虑一个自定义.npmrc文件，该文件可以自动指定某些参数（例如--save或--save-exact），而无需开发人员记住它们。我谈论 自定义.npmrc文件如何工作 在另一篇文章中。

N.B.如果确实陷入了使用依赖项的陷阱，而没有将其正确存储在package.json中，则只需使用--save（或类似）标志再次安装它。然后让每个开发人员运行一个npm更新，以确保每个人都使用相同的版本。

陷阱- using caret 依存关系 without thinking about it

添加npm软件包时，默认设置是使用脱字符号依赖项。但是，插入号和代字号依赖项都给开发过程带来了风险（但也可能有好处）。如果你’不熟悉使用尖号或波浪号的版本号，请阅读 我的背景文章 要么 NPM文档中的语义版本控制（Semver）.

简短地说，脱字符号（^）表示可接受（但不包括）4.0.0以下的任何版本。像这样的插入符依赖性 是npm的默认设置，但可能会导致危险，因为在该版本范围内可能会进行各种更改，可能包括破坏性更改，具体取决于软件包作者的处理方式。并非每个人都遵循semver规则。因此，这意味着在团队开发中，团队中的一个人可以使用3.1.1和另一个3.9.9（即，发布相同主要版本，但使用不同次要版本的版本），具体取决于每个上个版本的运行时间 npm更新 command. So, there can be lots of variability from caret 依存关系 like these.

波浪号依存关系（〜）相似，除了此处的范围更窄–因此〜3.1.1允许的任何版本不超过（但不包括）3.2.0（即，发布的主要/次要版本相同，但补丁版本不同）。

还要注意我’m在这里略微简化了事情，因为当版本号中使用零时，npm处理事情的方式有所不同。见 塞姆弗 页面以获取更多详细信息。

So are caret and tilde 依存关系 always bad?

好吧，不是。您可能会决定在开发过程中确实要使用最新和最好的库，而不必麻烦地单独管理每个库。通常，您确实确实确实希望这些小错误修复和性能增强。– and avoiding “exact”依赖关系给你（只要你 npm更新 经常）。

建议–做出是否要的明确决定“floating” 依存关系 in 开发者.

如果否，请考虑以下选项：

• Ensure all 开发者elopers always use the –保存精确标志而不是–save flag
  • This will have the effect of writing in an 精确 reference into package.json, rather than a caret 要么 tilde dependency
  • 在团队中使用自定义的.npmrc文件具有相同的效果（开发人员无需记住–每次安装软件包时都保存精确）
• 再次，看到我的 SPFx-node_modules，package.json和其他节点概念的概述 有关此技术的详细信息

如果是，则：

• 坚持插入符号依赖性，但考虑成为“tighter”在您发布Web部件时–确保所有开发人员正在运行 npm更新 regularly, and perhaps switch to 精确 依存关系 just before 运输.

Whether you use 精确 依存关系 in 开发者 要么 not, there’我建议您总是在每次发行时冻结相关性，’s to run npm收缩包装。我们’接下来再说。

陷阱– not locking down 依存关系 when you make a release

In SPFx and node.js 开发者elopment, it’重要的是要记住node_modules文件夹是一个完整的文件夹 树 of 依存关系. First level 依存关系 that you know about have their 拥有 依存关系, which are stored in 儿童 node_modules文件夹– that’s为什么node_modules文件夹可以很大并且很深。我们的步骤’到目前为止，您已经讨论过，例如考虑使用--save-exact以避免插入符/波浪号依赖性，只会使您到目前为止– and that’，因为它们仅处理您的第一级依赖项。因此，你’会发现很难重新创建作为v1发行的* 精确 *版本，因为您可以’t还原您在构建时拥有的确切的node_modules文件夹。相信你 可以 如果您始终将每个版本的整个mode_modules文件夹都检查到源代码管理中，那真是糟糕！

您需要的是整个 树 of 依存关系 to be frozen for each release – npm收缩包装命令给你这个。它创建一个JSON文件，其中包含所使用的每个软件包的哪个版本的详细信息：

此后，如果对包含此类文件的文件夹使用了npm install或npm update命令（命名为 npm-shrinkwrap.json），npm将使用它来还原软件包。这与默认行为不同，默认行为将使用package.json文件中指定的任何插入符号或代字号依赖项（等）。因此，使用这种方法，您可以还原整个构建在某个时间的状态，而无需使node_modules文件夹当时处于其状态。

建议–每次发布代码版本时，请运行npmrinkwrap。将npm-shrinkwrap.json存储在源代码管理中。

概要

Creating SharePoint Framework solutions effectively involves more than just learning the 新 APIs. 您 need to build a good understanding of the underlying web stack, and arguably some elements are more important than others –我建议您将模块，软件包和npm组合在一起使用。没有这个，它’开发或交付SPFx解决方案时，很容易陷入一些陷阱。总体而言，我建议：

• Taking care when 开发者elopers add libraries –确保在package.json中对其进行跟踪
• 决定你是否’re happy with 漂浮的 依存关系 during 开发者, 要么 whether you prefer to use 精确 依存关系
• 每次发布解决方案的版本时，都要运行npmrinkwrap，并将npm-shrinkwrap.json文件检入源代码管理。这样就可以在以后从未发布依赖项版本的情况下，正确地重建应用程序

SPFx-node_modules，package.json和其他节点概念的概述

N.B.这是一个伴随帖子 Avoiding dependency issues in SharePoint Framework (SPFx) 开发者elopment

任何有用的SharePoint框架（SPFx）解决方案都将使用外部JavaScript库–无论是较大的框架（例如React或Angular），还是较小的，更集中的库（例如LoDash，moment.js或其他）。由于SPFx基于基于node.js的Web堆栈，因此将此类库集成到您的解决方案中的最佳方法通常是从 npm，基于Internet的JavaScript软件包管理器。 Npm实际上等效于.NET世界中的NuGet。一旦您’用npm重新设置，开发人员只需运行 npm安装 jQuery的 [或其他] 软件包的源代码将添加到您的应用程序中’的文件。与节点开发一样，该库将添加到“node_modules”子文件夹，现在可以在您的代码中引用它。

node_modules文件夹的作用

So the node_modules folder stores all your 依存关系. But it also stores any 依存关系 of 那些， 等等等等。所以’可能很深的树形结构。例如，使用jQuery和React的应用程序可能看起来像这样：

在此示例中，jQuery依赖于“cache-swap”, which also has 它的 拥有 依存关系 in 它的 node_modules文件夹。等等..

您的代码实际使用的模块随您的应用程序一起分发，因此一切都在运行时正常工作。 SharePoint Framework工具中内置的捆绑机制使用以下方法来解决此问题： 网络包.

Ensuring 依存关系 are tracked with package.json

如果 - 保存 当添加带有 npm安装，则将条目写入 package.json 应用程序中的文件’的目录。这进入“dependencies”部分，看起来像这样：

"jquery": "^3.1.1"

这里’s一个完整的package.json文件的示例：

请注意上面那个版本号中的插入符号（^）。一世’稍后将讨论代字号和插入符的依赖关系。但是目的是 –save 标志是确保已记录依赖项。 node_modules文件夹本身通常*未*签入到源代码控制中（与所有NuGet软件包都不会采用相同的方式），部分原因是它很大且笨拙。相反，每个开发人员在他们的计算机上都有一个本地副本，并且共享的package.json文件在确保所有开发人员具有相同的文件中起着至关重要的作用。当其他开发人员随后从源代码管理中获取文件时，请运行 npm安装 要么 npm更新 commands will ensure all 依存关系 are restored on his/her machine, based on what’存储在package.json文件中。

我详细介绍 Avoiding dependency issues in SharePoint Framework 开发者elopment, 如果开发人员忘记跟踪依赖性（带有--save标志或类似标志），则其他开发人员可能会丢失其计算机上的模块，并且代码对他们不起作用– they’会得到一个缺少的模块错误。但是，即使开发人员确实记得要指定--save标志，您也会在dev中遇到问题，因为 npm uses caret 依存关系 by default，这些是“floating version” dependency. I won’在这里不进一步讨论陷阱，因为我们’关于这篇文章的基本概念–但是与此相关的是语义版本控制（称为semver）的整个主题。

语义版本控制的简要概述

Semver是指npm软件包可以使用的不同类型的版本号。的 npm文档中的semver页面 建议阅读，但是我’d说出您需要了解的核心内容：

• 3部分版本号格式，即MAJOR.MINOR.PATCH，以及应更新每个编号的规则– see http://semver.org
• package.json中使用的不同形式的版本号

版本号形式包括：

类型	例	它能做什么
插入符依赖性	^ 3.1.1	允许同一主版本上的任何版本，即低于4.0.0的任何版本
波浪号依赖性	~3.1.1	允许使用同一次要版本上的任何版本，即低于3.2.0的任何版本

但是，我的上表只是一个简化，因为如果版本号为零，则npm处理事情的方式有所不同。此外，npm也支持其他形式，例如预发行版本，例如“1.0.0-alpha.1” and 标签。我建议花时间在npm文档中，但是如果您喜欢其他格式，例如互联网上也有很多简化的帖子。 //nodesource.com/blog/semver-tilde-and-caret

Setting npm defaults to get consistency across 开发者s

在其他地方’ve讨论了传递给npm命令的参数，例如与npm install一起使用的--save或--save-exact标志。但是，对于开发团队来说，一种有用的方法是在整个团队中设置默认值，这样每个开发人员都不必在每次运行命令时都记住某个标志。这可以通过以下两种方式完成：

• 在每台机器上设置环境变量
• 使用.npmrc文件–在项目，用户或全局级别

我喜欢在用户级别（例如，我的计算机上的C：\ users \ chris \ .npmrc）使用.npmrc文件的想法，并确保所有团队成员都将其安装到位。通过创建/编辑此文件，例如，我可以指定所有依赖性都应使用* 精确 *版本号保存到package.json中，而不是插入符号或波浪号依赖性。我可以通过在文件中添加以下内容来做到这一点：

保存= true
保存-exact = true

Now, when any 开发者 installs a package, the following differences to the default behaviour will occur:

• The dependency will automatically be added to package.json, even if the 开发者 accidentally forgets the - 保存 flag
• The dependency will be added with an 精确 version number, not a caret version number

This is useful, as 开发者s won’不小心掉入了npm默认值可能导致的一些陷阱。

还检查了 保存前缀 config flag as an option to override caret 依存关系 (e.g. to change to tilde 依存关系).

概要

Hopefully this is some useful background information to concepts underneath the SharePoint Framework. It can seem a whole 新 world in some respects, but 在 the same time I don’认为您必须是npm，模块，webpack等方面的完整专家才能提高工作效率。尽管我认为，建议对这些子主题进行一些额外的挖掘。玩得开心！

Changes to Custom 动作 and handling of JavaScript in SharePoint Online

最近，我们的自定义操作停止在Office 365中的现代文档库中工作。对此感到惊讶，因为据我们所知，’不要做任何不利的事情“new”有关使用现代团队网站和现代文档库的指南。从现代文档库开始，就不支持使用ScriptSrc或ScriptBlock的自定义操作（与JSLink自定义相同）。但是我们当时’不要做任何这些事情–我们的具体细节是：

• 使用基于URL的操作的自定义操作，该操作打开了模式对话框（弹出窗口）–在我们的情况下，向用户显示自定义选项页面
• 用于“EditControlBlock”作为位置，因此我们的菜单项出现在每个文档的上下文菜单中
• 在我们的网站上注册“base document”我们的文档库中使用的内容类型

一段时间以来，一切都很棒-正如预期的那样，我们的菜单项同时出现在经典和现代文档库中。但是，在12月初（2016年），我们的菜单项（最终）从现代体验中消失了。这些图像显示了我们的菜单项（名为“Actions”）在经典视图中可见，但在现代视图中不可见：

经典：

现代：

New rules for Custom 动作

Essentially, Microsoft have made changes in 精确ly what is supported with Custom 动作. I guess you 可以 say this doesn’将100％与该主题的先前指南保持一致–或至少某些低级细节含糊不清或易于解释。例如， 现代文献库和可扩展性的最新进展 博客文章说：

“We’在这里已经取得了一些良好的进展。 主题，全球导航链接， 现代文档库体验已经支持扩展功能区和上下文菜单的基于URL的自定义操作。 这确保了利用这些功能的客户和合作伙伴可以使用现代文档库体验，而不会影响其自定义设置。”

就我们而言，我们认为我们应该没事，因为我们 ’重新使用URL（而不是ScriptSrc或ScriptBlock）。但是，与Office 365工程团队交谈后，很明显 包含JavaScript的URL （例如，网址=’javascript：OpenDialog（）’）不再被允许–尽管这一直有效到12月初。 另外， 按内容类型定位不再有效 –当前唯一的选择是按列表模板类型作为目标，例如：

• 100– custom list
• 101– document library
• ..等等

更新–现在可以再次按内容类型定位。因此，您可以再次按内容类型或列表模板类型作为目标。

我感谢产品小组中的人的帮助，他们帮助我了解了他们的代码目前正在做什么，以及将来的发展方向– thanks guys.

无论如何，我们必须进行一些更改。在我们的情况下，由于我们无法再从菜单中打开对话框（因为需要一些JavaScript），因此我们’重新改变我们的体验，以将用户导航到整个页面。另外，我们需要将定位方式从内容类型更改为列表模板类型– that’基本上可以，但是实际上确实为我们提供了与我们真正想要的范围稍有不同的范围。

这些变化会影响到您吗？如果是这样，你’我可能已经注意到– but either way, it’SharePoint开发人员明确了解该领域的最新发展绝对是值得的。总体而言，这类列表的内容更长，而现代列表和库不再支持这些内容，包括：

• 自定义母版页
• JSLink（字段和视图类型）
• AlternateCssUrl
• Custom 动作 which use ScriptLink to add JavaScript to the page

好的一面是，现在有一些MSDN文章形式的官方文档，它们提供了比我更多的细节。’米包括这里。我强烈建议您仔细阅读以下内容：

• 客制化"modern" lists and libraries （与本文最相关）
• 客制化"modern" team sites
• 客制化"modern" site pages

使用经典体验作为解决方法

当然请记住，这些更改不会’影响经典体验。如果您选择继续使用它（例如，在租户级别上设置），’对此感到高兴。我们当时’t unfortunately, because we want our uses to have the benefits of the 新 document library UX (better mobile experience, improved metadata editing, 新 summary panel, sorting/filtering enhancements and so on).

展望未来（尤其是围绕Office 365中的JavaScript）

Microsoft have noted in several places that 新 mechanisms will come to SharePoint Online to match many of the previous capabilities. They may not take 精确ly the same form as the previous mechanisms, but it should be possible to achieve the same overall result. These include:

• 自定义母版页-> some other “deep branding”控制（可能会或可能不会提供控制 充分 HTML）
• JSLink->其他一些机制来控制列表视图和字段的呈现
• CustomAction + ScriptLink->其他将JavaScript添加到页面的机制

我特别考虑JavaScript’显然，将增加管理员对脚本批准的控制–这样做的想法是提供更多的管理，以便开发人员在未经广泛批准的情况下不能添加任意脚本。毕竟’s为什么Microsoft进行了一些最近的更改以撤消以前支持的方法–他们确实留下了漏洞，可能会给某些组织带来麻烦。尽管旅途中偶尔会遇到痛苦，但我认为我们所有人都必须接受这些变化使情况变得更好，并且由此产生的总体状况应该更好。