SharePoint 加载项更新过程SharePoint Add-ins update process

如果你要添加功能、修复 Bug 或进行安全更新,则必须更新 SharePoint 外接程序。将通过部署第一个版本的外接程序的相同方式在 SharePoint 外接程序包中部署对外接程序的更新。SharePoint 外接程序更新过程确保在更新因任何原因失败时保留外接程序的数据。You have to update a SharePoint Add-in if you add functionality, fix a bug, or make a security update. An update to an add-in is deployed in a SharePoint Add-in package in the same way that the first version of the add-in is deployed. The SharePoint Add-in update process ensures that the add-in's data is preserved if the update fails for any reason.

重要

无法使用更新系统更改加载项类型You cannot change the add-in type by using the update system. 例如,无法通过更新将加载项类型从 SharePoint 托管更改为提供商托管。For example, you cannot change an add-in from SharePoint-hosted to provider-hosted with an update. 若要更改类型,需要从旧加载项迁移到新加载项To make a change of type, you need to migrate from an old add-in to a new one. 特别是,由于自动托管加载项的预览计划已关闭,因此应注意无法将自动托管加载项更新为提供商托管加载项。In particular, because the preview program for autohosted add-ins has been closed, you should be aware that you cannot update an autohosted add-in to a provider-hosted add-in. 应按照将自动托管 SharePoint 加载项转换为提供商托管加载项中说明操作,转换加载项。You have to convert the add-in as explained in Convert an autohosted SharePoint Add-in to a provider-hosted add-in.

SharePoint 加载项更新过程Update process for a SharePoint Add-in

对于更新,在外接程序清单中使用原始版本中使用的同一产品 ID。外接程序清单中的版本号应大于原始外接程序或最新更新的版本号。For an update, you use the same product ID in the add-in manifest that you used for the original version. The version number in the add-in manifest should be greater than the version number of the original add-in or the most recent update.

将更新上载到组织外接程序目录后的 24 小时内,以及在将其上载到 Office 商店后的一周内,在每个安装了该应用程序的网站的"网站内容"页上,外接程序列表旁将显示更新可用的指示。用户可单击链接更新外接程序,如图 1 所示。可用更新还会在租户管理 UI 中显示。Within 24 hours after you upload your update to an organization's add-in catalog, and within a week of uploading it to the Office Store, an indication that an update is available appears next to the add-in's listing on the Site Contents page of every website where it is installed. Users can click a link to update the add-in as shown in Figure 1. Available updates are also exposed in the tenant management UI.

图 1:SharePoint 加载项升级过程Figure 1. Add-in for SharePoint upgrade process

在 UI 上更新应用的步骤

提示

开发更新时,并不希望每次将新版本上传到测试 SharePoint 加载项目录时都要等待 24 小时。When you are developing an update, you don't want to wait 24 hours every time you upload a new version to your test SharePoint add-in catalog. 若要了解如何立即更新加载项,请参阅更新加载项无需等待 24 小时For information about how to immediately update an add-in, see Update an add-in without waiting 24 hours .

默认情况下,SharePoint 会每 24 小时检查一次已安装加载项是否有更新。场管理员可以使用下面的 SharePoint 命令行管理程序命令(其中,n 是检查间隔小时数),将此频率设置为其他值:By default, SharePoint checks every 24 hours for updates to installed add-ins. A farm administrator can set this to another value by using the following SharePoint Management Shell command, where n is the number of hours between checks:

Set-SPInternalAppStateUpdateInterval -AppStateSyncHours n

如果将此值设为 0,则会在每次执行内置计时器作业内部加载项状态更新时进行检查,默认为每小时执行一次。If the value is set to 0, the check is made every time the built-in timer job Internal Add-in State Update executes, which by default is every hour. 使用管理中心,场管理员可以更改计时器作业的执行频率,也可以立即运行它。Farm administrators can use Central Admin to change the frequency of the timer job or run it immediately.

如果用户安装 SharePoint 加载项更新,SharePoint 会执行以下操作。SharePoint will do the following when a user installs an update to a SharePoint Add-in. 这些事件并非一定会完全按照下列顺序发生,其中部分事件可能会并行发生。These events do not necessarily occur in exactly this order, and some of them may occur in parallel. 此外,如果更新失败,还会执行完全回滚。Also, if an update fails, there is a complete rollback.

  • SharePoint 提示用户批准授予加载项请求的权限。SharePoint prompts the user to approve permissions requested by the add-in.

  • SharePoint 使外接程序对用户暂时不可用。SharePoint makes the add-in unavailable to users temporarily.

  • 如果外接程序包含 SharePoint 解决方案包 (.wsp),并且该解决方案包中的内容已通过任何方式更改,则 SharePoint 将执行下列操作:If the add-in contains a SharePoint solution package (.wsp), and the contents of the solution package have changed in any way, SharePoint does the following:

    • 备份加载项 Web(但在 SharePoint Online 和本地 SharePoint 2016 及更高版本中,只有在更新导致列表架构发生变化时,才需要备份 SharePoint 列表中的实际数据)。Makes a backup of the add-in web (but, in SharePoint Online and in on-premises SharePoint 2016 and later, the actual data in SharePoint lists is backed up only if the update is making a change in the list's schema).

    • 测试对备份的更新。Tests the update of the backup.

    • 如果测试成功,更新原始加载项 Web。If the test succeeds, updates the original add-in web. 请注意,加载项包中的新 .wsp 文件用于更新加载项 Web 中的功能和其他元素(功能架构的更新部分已在 SharePoint 中扩展)。Note that the new .wsp file in the add-in package is used to update the Features and other elements in the add-in web (the update parts of the Feature schema have been expanded in SharePoint).

  • SharePoint 执行 UpgradedEventEndpoint Web 服务(如果已在加载项清单中注册的话)。SharePoint executes the UpgradedEventEndpoint web service, if any is registered in the add-in manifest.

    备注

    若为提供商托管加载项,请为加载项的所有非 SharePoint 组件提供更新逻辑。If the add-in is provider-hosted, you provide the update logic for all the non-SharePoint components of the add-in. 这些组件多半是与 SharePoint 加载项本身分开更新,就像这些组件是与加载项分开安装一样。For the most part, you update these components separately from the update of the SharePoint Add-in itself, just as you installed these components separately from the installation of the add-in. 不过,一些更改可能只会在用户更新 SharePoint 加载项时才生效。But there may be some changes that should only happen when a user is updating the SharePoint Add-in. 此逻辑可纳入 UpgradedEventEndpoint Web 服务或加载项本身的更新后首次运行逻辑。This logic can go in an UpgradedEventEndpoint web service or in first-run-after-update logic of the add-in itself.

  • SharePoint 让加载项及其组件再次可用。SharePoint makes the add-in and its components available again.

备注

若要更改加载项 Web 中任何列表的架构,请将列表与加载项 Web 的其余部分一起备份。If the schema of any list in the add-in web is being changed, the list is backed up along with the rest of the add-in web. 若有大量列表数据,备份可能需要一段时间才能完成。This can take some time if there is a lot of data in the list. 如果无法在一小时内完成更新过程,将会停止并回滚更新。If the update process cannot complete in one hour, it stops and the update is rolled back.

从旧加载项迁移到新加载项Migrating from an old add-in to a new one

在某些情况下,建议生成全新的加载项,从而替换旧加载项,而不是更新原始加载项。In some scenarios you may want to produce an entirely new add-in to replace an old one, rather than update the original one. 虽然新加载项可以采用与旧加载项一样的易记名称,但必须在加载项清单中为它指定新产品 ID,并且它必须在公共 Office 应用商店和 SharePoint 网站的“添加加载项”**** 页中作为与原始版本不同的项显示。The new add-in can have the same friendly name as the old, but it must be given a new product ID in the add-in manifest, and it appears in the public Office Store and on the Add an Add-in page of SharePoint websites as a distinct item from the original version.

备注

组织加载项目录中的项是按照加载项包的文件名(而不是按照产品 ID 或加载项名称)进行区分。Items in an organization's add-in catalog are distinguished by the file name of the add-in package, not the product ID or the name of the add-in. 如果新加载项采用与旧加载项一样的包文件名,便会在加载项目录中替换旧加载项,并且旧加载项不会再显示在“添加加载项”**** 页上。If the new add-in has the same package file name as the old, it replaces the old one in the add-in catalog, and the old add-in no longer appears on the Add an Add-in page. 如果将加载项包上传到目录时还为它启用了版本控制,那么旧版文件(即旧应用)仍会保留在项历史记录中。If you enable versioning on the add-in package when you upload it to the catalog, the old version of the file (which is the old app) is still available in the item's history. 可以下载或还原为旧加载项包,但无法在目录或“添加加载项”**** 页上将新旧加载项作为不同的项同时显示,除非它们的文件名不同。You can download the old add-in package or revert to it, but there is no way to have both the old and new add-ins as separate items in the catalog or on the Add an Add-in page, unless they have distinct file names.

在某些情况下,您可能需要迁移数据。例如,新的外接程序可能使用具有不同于旧外接程序的架构的 Microsoft Azure SQL 数据库。或者新外接程序可能使用不同的数据存储机制;例如,外部数据库而不是 SharePoint 列表。您必须为数据迁移提供代码。In some cases, you might need to migrate data. For example, the new add-in might use a Microsoft Azure SQL Database that has a different schema from the old add-in. Or the new add-in might use a different data storage mechanism; for example, an external database instead of SharePoint lists. You must provide the code for data migration.

如果旧数据位于远程事件处理程序可以访问的位置,则可以在新外接程序的 InstalledEventEndpoint Web 服务中实现迁移逻辑。或者,如果新外接程序可以访问旧数据,则可将迁移逻辑置于用户启动新外接程序时首次运行的代码中。如果远程处理程序或新外接程序均无法访问旧数据,则可创建旧外接程序的更新,以添加数据导出功能和该功能的 UI。用户首先更新旧外接程序,然后使用它将数据导出到新外接程序可访问的位置。在新外接程序中添加功能和 UI 以导入数据。If your old data is somewhere that can be accessed by a remote event handler, you can implement migration logic in an InstalledEventEndpoint web service of the new add-in. Alternatively, if the new add-in has access to the old data, you can put the migration logic in code that runs the first time that a user starts the new add-in. If the old data cannot be accessed by either the remote handlers or the new add-in, you can create an update of the old add-in that adds a data export capability and a UI for the capability. Users would first update the old add-in, and then use it to export the data to a location where the new add-in can access it. You include the capability and UI to import data in the new add-in.

原则上,您可在新的外接程序中重复使用旧外接程序中使用的外部数据源、计算组件或其他外部组件。但是,请考虑一下,卸载 SharePoint 外接程序时,SharePoint 基础架构将卸载其安装的所有内容。因此,SharePoint 外接程序仅依赖于它所安装的组件或者不由 SharePoint 基础架构安装的外部组件通常是很好的做法。In principle, you can reuse an external data source, compute component, or other external component in the new add-in that was used in the old add-in. Consider, however, that when a SharePoint Add-in is uninstalled, the SharePoint infrastructure will uninstall everything that it installed. Accordingly, it is generally a good practice for a SharePoint Add-in to depend on only components that it installed or external components that were not installed by the SharePoint infrastructure.

备注

建议如果实现安装组件的 InstalledEventEndpointUpgradedEventEndpoint,也应实现卸载这些相同组件的 UninstallingEventEndpointWe recommend that if you implement an InstalledEventEndpoint or an UpgradedEventEndpoint that installs components, you should also implement an UninstallingEventEndpoint that uninstalls those same components. 这样做符合加载项应为独立式且进行干净卸载的设计原则。Doing so conforms to the design principles that add-ins should be self-contained and uninstall cleanly. 不过,不得删除在加载项卸载后对用户仍有用的数据。However, data that would still be useful to users after the add-in is uninstalled should not be deleted. 加载项创建的网站(而不是加载项 Web)通常应视为数据。Websites created by an add-in, other than the add-in web, should usually be considered data.

如果旧外接程序和新外接程序均包含一个外接程序 Web,则考虑在安装新外接程序时创建一个新的外接程序 Web。因此,您不应在 SharePoint Feature 架构中使用与更新相关的 XML 标记。此类标记不起作用,因为您不会更新现有 SharePoint 组件;而是将旧外接程序更换为新外接程序。If the old and new add-ins each contain an add-in web, consider that a new add-in web is created when your new add-in is installed. For this reason, you should not use the update-related XML markup in the SharePoint Feature schema. Such markup does not work because you are not updating existing SharePoint components; you are replacing an old add-in with a new one.

另请参阅See also