SharePoint 加载项体系结构和开发前景的重要方面Important aspects of the SharePoint Add-in architecture and development landscape

本文对 SharePoint 加载项一文中的信息进行了补充。 This article supplements the information in the article SharePoint Add-ins.

SharePoint 外接程序模型提供以下方法来托管 SharePoint 外接程序的组件:The SharePoint Add-in model provides the following ways to host the components of a SharePoint Add-in:

  • 提供程序承载: 加载项至少包括一个远程组件,并且还可能包括 SharePoint 托管的组件。非 SharePoint 组件按您的硬件或云帐户的逻辑进行部署,或者使用您提供的安装程序和说明在客户的硬件或云帐户上部署。Provider-hosted: Add-ins that include at least one remote component and may also include SharePoint components. The non-SharePoint components are deployed by your logic on your hardware or cloud account, or deployed on the customer's hardware or cloud account using installation programs and instructions that you provide.

  • SharePoint 托管: 加载项仅包含 SharePoint 组件和在客户端上运行的逻辑。SharePoint-hosted: Add-ins that include only SharePoint components and logic that runs on the client.

若要详细了解托管选项以及如何选择这些选项,请参阅选择用于开发和托管 SharePoint 加载项的模式For more detailed information about hosting options and some guidance for how to choose between them, see Choose patterns for developing and hosting your SharePoint Add-in.

加载项中的加载项 Web、主机 Web、功能和 SharePoint 组件Add-in webs, host webs, Features, and SharePoint components in add-ins

将 SharePoint 加载项安装到的网站称为“主机 Web”。The website to which a SharePoint Add-in is installed is called the host web. 不过,SharePoint 加载项的重要组成部分(无论是 SharePoint 组件,还是外部组件)都不会部署到主机 Web。However, the significant parts of the SharePoint Add-in, whether they are SharePoint components or external components, are not deployed to the host web. 外部组件部署到外部服务器或云帐户。External parts are deployed to external servers or cloud accounts. SharePoint 组件部署到有自己域的特殊网站。SharePoint components are deployed to a special website with its own domain. 这就称为“加载项 Web”。This is called the add-in web.

仅一组数量有限的 UI 元素部署到主机 Web,这些元素向用户授予对加载项的其他组件的访问权限。Only a limited set of UI elements that give users access to the add-in's other components are deployed to the host web. 主机 Web 中的这些 UI 组件部署到主机 Web 功能中,这是加载项包(而不是 .wsp 文件)内的宽松功能。These UI components in the host web are deployed as part of a host web Feature—a Feature that is loose in the add-in package instead of inside a .wsp file. 部署到加载项 Web 的组件始终部署到 .wsp 文件内的功能中。The components that are deployed to the add-in web are always in Features that are inside a .wsp file. 这两种功能都必须有 Web 范围。Both kinds of Features must have Web scope. SharePoint 加载项中的功能不可能有其他任何范围。No other scope is possible for Features in SharePoint Add-ins.

一般情况下,可以将任何不包含在 SharePoint 服务器上运行的自定义代码的 SharePoint 组件添加到 SharePoint 加载项(并部署到加载项 Web)。As a general rule, any SharePoint component that does not include custom code that runs on the SharePoint servers can be included in a SharePoint Add-in (and be deployed to the add-in web). 不过,在组件的部署方式和位置方面,存在一些例外情况和细微差别。There are, however, some exceptions and some nuances to how and where the components are deployed. 若要详细了解这些细微差别以及加载项中的主机 Web、独立加载项 Web 和功能,请参阅 SharePoint 中的主机 Web、加载项 Web 和 SharePoint 组件For more information about these nuances and about host webs, the isolated add-in webs, and Features in add-ins, see Host webs, add-in webs, and SharePoint components in SharePoint.

通过 UI 访问加载项Accessing the add-in from the UI

在网站上安装 SharePoint 外接程序后,会在主机 Web 的"网站内容"页面上列出该加载项。用户可以从该页面中启动此加载项。以这种方式打开时,该加载项将在全屏模式下运行。When a SharePoint Add-in is installed on a website, the add-in is listed on the Site Contents page of the host web. Users can start the add-in from that page. When opened in this way, the add-in runs in full-screen mode.

SharePoint 加载项的另一种呈现方式是通过加载项部件,即 ClientWebPart 类表示的 Web 部件类型。Another way that a SharePoint Add-in can be surfaced is through an add-in part, a type of web part that is represented by the ClientWebPart class. 这种类型的 Web 部件其实就是托管加载项页面的 IFrame 包装器。This kind of web part is essentially a wrapper for an IFrame that would host a page of the add-in. 在最简单的情况下,Web 部件的唯一重要属性是指向该页面的 URL。In the simplest case, the only significant property of the web part is a URL that points to the page.

不过,Web 部件也可以有自定义属性,用户能够在“工具部件”中设置这些属性。But web parts can have custom properties that users can set in a Tool Part. 例如,此类属性可用于设置上下文信息,如用户的邮政编码。Such properties could be used, for example, to set context information such as the user's ZIP Code or Postal Code. 若要在加载项中添加此类加载项部件,请在加载项中创建主机 Web 功能,并添加声明性 Web 部件标记。To include such an add-in part in your add-in, you create a host web Feature in the add-in and add declarative web part markup. 与其他任何 Web 部件类似,它会显示在 SharePoint UI 中,用户可以从中添加 Web 部件。Like any other web part, it appears in the SharePoint UI from which users add web parts. 如果需要更多可变性,可以与加载项一起部署多个加载项部件。You can have more than one add-in part deployed with your add-in if you need even more variability. 例如,在天气加载项中,可以使用一个加载项部件显示当前天气,并使用另一个加载项部件显示每周天气预报。For example, a weather add-in can have an add-in part that shows current weather and a second add-in part that shows a weekly forecast. 两个部件的尺寸和功能可以不同。The two parts can have different sizes and functionality.


你也可以将加载项部件部署到加载项 Web。若要执行此操作,Web 部件的标记应该是加载项包中 .wsp 文件内部的功能的一部分,而不在主机 Web 功能内。You can also deploy add-in parts to the add-in web. To implement this, the markup for the web part would be part of a Feature inside a .wsp file in the add-in package, not in the host web Feature.

建议尽可能尝试为加载项设计 SharePoint 外观,尽管这不是一项强制性要求,也不一定是最佳选择。We recommend that you try to give your add-ins a SharePoint appearance to the extent possible, although that is not mandatory and may not always be the best choice. 若要详细了解用户体验指南,请参阅 SharePoint 加载项的用户体验设计For more information about the user experience guidelines, see UX design for SharePoint Add-ins.

例如,存在一个名为 app.master 的特殊母版页。此页面经过了优化以供加载项页面使用。此 app.master 页面是 SharePoint 中所包括的新网站定义的一部分。There is, for example, a special master page called app.master. This page is optimized for use by the pages of add-ins. The app.master page is part of a new site definition that is included in SharePoint.

另一种有助于加载项保持与 SharePoint 一致的外观的工具是,SharePoint 随附的部件版式控制。Another tool you can use to help your add-ins maintain a consistent look and feel with SharePoint is the chrome control that ships with SharePoint. 借助此控制,可以将 SharePoint 导航标题区域添加到加载项页面(包括外部托管的页面)。This control enables you to add the SharePoint navigation header area to your add-in pages, including pages hosted externally. 若要详细了解 SharePoint 加载项中的用户体验设计,请参阅 SharePoint 加载项的用户体验设计。若要详细了解部件版式控制,请参阅在 SharePoint 加载项中使用客户端部件版式控制For more information about UX design in SharePoint Add-ins, see UX design for SharePoint Add-ins. For more information about the chrome control, see Use the client chrome control in SharePoint Add-ins.

加载项包结构Add-in package structure

SharePoint 加载项包是文件扩展名为“.app”且符合开放打包约定 (OPC) 的文件。A SharePoint Add-in package is a file that has an ".app" extension and that complies with the Open Packaging Conventions (OPC). (此文件的打开方式为,先添加“.zip”作为文件名的额外扩展名,再在 Windows 资源管理器中打开文件)。其中包含加载项清单,指定了加载项的特定属性和 SharePoint 安装基础结构说明。(You can open the file by adding ".zip" as an extra extension on the filename and then opening it in Windows Explorer.) It contains an add-in manifest that specifies certain properties of the add-in and instructions to the SharePoint installation infrastructure. 若要详细了解加载项清单和加载项包,请参阅了解 SharePoint 加载项应用清单结构和加载项包For more information about the add-in manifest and package, see Explore the app manifest structure and the package of a SharePoint Add-in.

SharePoint 加载项的权限、身份验证和授权Permissions, authentication, and authorization for SharePoint add-ins

SharePoint 引入了新的加载项权限和安全系统。SharePoint introduces a new add-in permissions and security system.

加载项权限Add-in permissions

SharePoint 外接程序具有权限,就像用户和组具有权限一样。这使加载项能够具有一组权限,这组权限不同于正在执行该加载项的用户的权限。SharePoint Add-ins have permissions just as users and groups do. This enables an add-in to have a set of permissions that are different from the permissions of the user who is executing the add-in.

您必须在加载项清单文件中请求加载项运行所需的权限。添加加载项的用户必须准许这些请求,用户只能授予作为用户所具有的权限。授予必须针对所有请求的权限,或者不针对任何权限,以简化用户和开发人员的权限管理。(加载项主体始终具有对加载项 Web 的完全控制权限,因此,它只需要请求对主机 Web 中或加载项 Web 外部其他位置中的 SharePoint 资源的权限。)You must request, in the add-in manifest file, the permissions that an add-in needs to run. The user who adds the add-in must grant these requests, and the user can only grant permissions that he or she has as a user. The grant must be for all the requested permissions or none of them to simplify the management of permissions for users and developers. (The add-in principal always has full control rights to the add-in web, so it only needs to request permissions to SharePoint resources in the host web or other locations outside the add-in web.)

若要详细了解加载项权限,请参阅 SharePoint 中的加载项权限For more information about add-in permissions, see Add-in permissions in SharePoint.

选择性委派和授权Selective delegation and authorization

无论是要启动加载项的用户,还是要向加载项授予对资源的访问权限的资源所有者,都无需向加载项提供自己的凭据或密码。Neither users who are launching an add-in, nor resource owners who are granting an add-in permission to access a resource, need to provide the add-in their credentials or password. 相反,SharePoint 支持用户和资源所有者仅授予加载项请求获取的特定权限。Instead, SharePoint enables users and resource owners to grant only the specific permissions that the add-in requests. 为此,SharePoint 使用事务协议 OAuth 2.0What makes this possible is the use by SharePoint of the transaction protocol OAuth 2.0. 若要详细了解 SharePoint 中的 OAuth,请参阅 SharePoint 加载项的上下文标记 OAuth 流For more information about OAuth in SharePoint, see Context Token OAuth flow for SharePoint Add-ins.

跨域访问Cross-domain access

如果 SharePoint 加载项包括使用 JavaScript 作为数据访问逻辑的远程 Web 应用,可以使用 JavaScript 跨域库,获取对安装加载项的租赁中 SharePoint 数据的授权访问权限。A SharePoint Add-in that includes a remote web application that uses JavaScript for its data access logic can use a JavaScript cross domain library to get authorized access to SharePoint data within the tenancy where the add-in is installed. 有关详细信息,请参阅使用跨域库从加载项访问 SharePoint 数据For more information, see Access SharePoint data from add-ins using the cross-domain library.

加载项生命周期Add-in lifecycle

SharePoint 加载项生命周期包括发布、安装、升级和卸载。The lifecycle for a SharePoint Add-in includes publishing, installing, upgrading, and uninstalling. 若要详细了解这些主题,请参阅发布 SharePoint 加载项部署和安装 SharePoint 加载项:方法和选项SharePoint 加载项更新过程For more information about these subjects, see Publish SharePoint Add-ins, Deploying and installing SharePoint Add-ins: methods and options and SharePoint Add-ins update process.

另请注意,租户管理员还可以使用一种机制,将 SharePoint 加载项批量安装到多个网站中。Note also that there is a mechanism by which tenant administrators can batch install a SharePoint Add-in to multiple websites. 有关详细信息,请参阅 SharePoint 加载项的租赁和部署范围For more information, see Tenancies and deployment scopes for SharePoint Add-ins.

SharePoint 加载项中的数据存储Data storage in SharePoint Add-ins

SharePoint 外接程序可以创建和访问任何种类的数据,包括结构化数据、文档和多媒体文件。此数据可以存储在 SharePoint 或外部位置中。SharePoint Add-ins can create and access any kind of data, including structured data, documents, and multimedia files. This data can be stored in SharePoint or in an external location.

结构化数据存储选项Structured data storage options

SharePoint 加载项可以在 SharePoint 内外以及 Microsoft 平台和非 Microsoft 平台上使用几乎任何一种结构化数据存储。A SharePoint Add-in can use almost any kind of structured data storage, both inside and out of SharePoint and on Microsoft and non-Microsoft platforms. 可以在下面列出的一些位置上存储 SharePoint 加载项的结构化数据:The following are some locations where you can store structured data for a SharePoint Add-in:

  • 加载项 Web 中的 SharePoint 列表SharePoint lists in an add-in web
  • SQL AzureSQL Azure
  • 通过 Microsoft Business Connectivity Services (BCS) 连接到 SharePoint 的外部数据源External data sources connected to SharePoint with Microsoft Business Connectivity Services (BCS)
  • 非 Microsoft 云服务A non-Microsoft cloud service
  • 自己服务器上的数据库A database on your own server


到一定时候可能会升级 SharePoint 加载项。You will probably upgrade your SharePoint Add-in at some point. 如果 SharePoint 加载项中的 SharePoint 组件部署到加载项 Web,升级过程会完整复制加载项 Web。When a SharePoint Add-in includes SharePoint components on an add-in web, the upgrade process makes a complete copy of the add-in web. 因此,如果加载项 Web 中的 SharePoint 列表非常大,便会让升级过程变得非常耗时,并占用内容数据库服务器上的大量处理器资源。For this reason, very large SharePoint lists on the add-in web make the upgrade process time-consuming and processor intensive on the content database server. 应避免向加载项 Web 上的 SharePoint 列表添加“大数据”。You should avoid putting "big data" in SharePoint lists on the add-in web.

非结构化数据存储选项Unstructured data storage options

由 SharePoint 外接程序生成或使用的文档、图像、视频、音频文件和其他类型的非结构化数据可存储在 SharePoint 的内部或外部。文档库是文档的最佳选择,并且可以通过 SharePoint 搜索来搜索文档库。网站资产库通常是多媒体文件的最佳选择。Documents, images, videos, audio files, and other kinds of unstructured data that is produced or used by a SharePoint Add-in can be stored in or outside SharePoint. Document libraries are a good choice for documents and are searchable via SharePoint search. A site asset library is often a good choice for multimedia files.

其他选项包括你的 Microsoft Azure 帐户中或你自己的服务器上的 Blob 存储。你还可以在一些非 Microsoft 平台上或云服务中存储文件。Other options include Blob storage in your Microsoft Azure account or on your own servers. You can also store files in some non-Microsoft platforms or cloud services.

加载项设置和其他元数据存储选项Add-in settings and other metadata storage options

可以在多个位置上存储 SharePoint 加载项的元数据(如用户首选项、位置信息和其他设置)。Metadata for a SharePoint Add-in, such as user preferences, location information, and other settings can be stored in several places. 隐藏 SharePoint 列表有时也是一个不错的选择。A hidden SharePoint list is sometimes a good choice. 还可以使用加载项 Web 的属性包。You can also use the property bag of the add-in web. 对于提供程序托管加载项,另一种选择是使用 Microsoft Azure 表存储。Another option, for a provider-hosted add-in, is to use Azure Table storage.

安全数据访问选项Secure data access options

当然,您的安全数据访问选项取决于您的存储选择。数据访问和搜索将在另外几篇文章中进行详细讨论。有关详细信息,请参阅 Secure data access and client object models for SharePoint Add-insYour options for secure data access, of course, depend on your choice of storage. Data access and search are discussed in detail in several other articles. For more information, see Secure data access and client object models for SharePoint Add-ins.

管理加载项Managing add-ins

网站集管理员和租户管理员可以监视加载项,以及更改分配给加载项的资源。此外,加载项存储的 Microsoft 人员可以标记加载项以及禁用加载项。Site collection administrators and tenant administrators can monitor add-ins and change the resources allocated to them. In addition, Microsoft personnel for the add-in store can flag add-ins and disable them.

若要详细了解如何管理加载项,请参阅 TechNet 上的安装和管理 SharePoint 加载项For more information about managing add-ins, see Install and manage SharePoint Add-ins on TechNet.

监视加载项Monitoring add-ins

SharePoint 支持监视加载项的运行状况,并在 UI 中显示此类信息,以供网站所有者、租户管理员和场管理员查看。SharePoint provides health monitoring of add-ins and makes this information available in the UI to website owners, tenant administrators, and farm administrators. 有关监视系统的大部分文档都位于 TechNet 上;例如监视 SharePoint 加载项。此部分只是简要概述了如何监视所销售的加载项。Most documentation for the monitoring system is on TechNet; for example Monitor SharePoint Add-ins. This section is just a quick introduction to explain how add-ins that you sell are monitored.

某些种类的数据是按应用程序报告的,而其他种类是按应用程序实例报告的。监视框架报告的主要项目如下:Some kinds of data are reported per-app and other kinds are reported per-app-instance. The primary items that the monitoring framework reports are as follows:

  • 加载项的使用情况,如已安装应用程序的次数(创建新实例)。Use of the add-in, such as the number of times it has been installed (creating a new instance).
  • 每个加载项实例的服务器资源消耗。Server resource consumption of each add-in instance.
  • 每个加载项实例的安装、升级和运行时错误。Installation, upgrade, and run-time errors of each add-in instance.
  • 每个加载项实例的整体运行状况指示器(绿色、黄色和红色)。An overall health indicator for each add-in instance of green, yellow, and red.

如果加载项包含 Azure 网站组件,监视框架还会每小时轮询一次 Azure,检查是否有错误数据,并在 SharePoint UI 中报告关键错误和存储配额数据。If the add-in includes Azure website components, the monitoring framework also polls Azure hourly for its error data and reports critical errors and storage quota data in the SharePoint UI. 但不会报告 Azure SQL 数据库错误。Azure SQL Database errors are not reported.

利用监视框架提供的信息,管理员可以确定其加载项采购预算是否精打细算,他们是否必须向加载项部署更多资源,以及他们是否必须禁用未正常工作的加载项。The information that is provided by the monitoring framework enables administrators to determine whether their add-in purchase budget is being wisely spent, whether they have to deploy more resources to add-ins, and whether they have to disable an add-in that is not working correctly.

注册加载项依赖项Registering add-in dependencies

如果您的 SharePoint 外接程序依赖不可用且无法在加载项 Web 上提供的 SharePoint 功能,它将无法正常运行,并且您的客户将抱怨。通过在加载项清单中注册您的加载项的依赖项,您可以确保在未提供必备服务和功能的情况下,不会安装您的加载项。SharePoint 外接程序的安装基础结构将检查这些必备组件,如果其中任一组件不可用,它将阻止安装您的加载项。If your SharePoint Add-in depends on a SharePoint capability that is not available and cannot be made available on the add-in web, then it will not work properly and your customers will complain. You can ensure that your add-in is not installed where the requisite services and Features are not available by registering the dependencies of the add-in in add-in manifest. The installation infrastructure for SharePoint Add-ins will check for these prerequisites and it will block installation of you add-in if any of them is not available.

对于 Excel、Access 或 Visio Services 等服务,基础结构会验证是否已安装并许可相应服务。For services, such as Excel, Access, or Visio services, the infrastructure will verify that the service is installed and licensed.

对于任务列表等功能,基础结构会验证相应功能是否已部署且:For Features, such as a Task list, the infrastructure verifies that the Feature is deployed and either:

  • 已在Web 应用网站(网站集)范围内激活activated at the Farm, WebApplication, or Site (site collection) scope


  • 可通过 Web 范围在安装加载项时创建的加载项 Web 上激活。activatable, with Web scope, on the add-in web that is created when the add-in is installed.


加载项安装基础结构会自动在创建的加载项 Web 上激活此类功能。The add-in installation infrastructure will automatically activate such Features on the add-in web when it is created.

下面各部分详细介绍了注册必备组件所需了解的信息。The following sections provide the details you need to register your prerequisites.

使用权限请求隐式注册依赖项Implicitly register dependencies with permission requests

当您的加载项需要访问加载项 Web 之外的 SharePoint 组件时,它必须在加载项清单的 AppPermissionRequests 部分请求访问这些资源的权限。这些权限请求还推动了必备组件注册,因为 SharePoint 将从您的加载项请求的权限推断加载项需要使用某些 SharePoint 功能。在许多情况下,SharePoint 可以推断您的加载项需要的所有功能,因此不必阅读本主题的其余各节。但是,额外的依赖项注册没有害处。When your add-in needs access to SharePoint components outside of the add-in web, it must request permission for these resources in the AppPermissionRequests section of the add-in manifest. These permission requests also serve as prerequisite registrations because SharePoint will infer from the permissions that your add-in requests that it the add-in needs certain SharePoint capabilities to be available. In many situations, SharePoint can infer all the capabilities that your add-in needs and the remaining sections of this topic are not needed. However, redundant dependency registrations are not harmful.

使用 AppPrerequisite 显式注册依赖项Explicitly register dependencies with AppPrerequisites

如果加载项的依赖项未由其权限请求暗示,请在加载项清单中使用 AppPrerequisite 元素注册各个依赖项。When your add-in has a dependency that is not implied by its permission requests, you register each dependency with an AppPrerequisite element in the add-in manifest. 此元素有下列三个属性:TypeID 和(可选)MinimumVersionThere are three attributes in this element: Type, ID, and (optionally) MinimumVersion.

Type 有下列三个可取的必备组件值:FeatureCapablilityAutoProvisioningThere are three possible prerequisite values for Type: Feature, Capablility, and AutoProvisioning. Feature 必备组件值就是指必须在加载项 Web 上或在包括加载项 Web 的更广范围内部署并激活的 SharePoint 功能。A Feature prerequisite is simply a SharePoint Feature that must be deployed and activated on the add-in web or a broader scope that includes the add-in web. Capability 是指一组必须在加载项 Web 上激活的相关功能和服务。A capability is a set of related Features and services that must be available on the add-in web. (将在下一部分中介绍 AutoProvisioning。)(AutoProvisioning is discussed in the next section.)

可选的 MinimumVersion 指定您的加载项需要的特性或功能的最低版本。此属性值采用 n.n.n.n 形式;例如 optional MinimumVersion specifies the lowest version of the Feature or capability that your add-in requires. The attribute values are of the form n.n.n.n; for example

ID 指定必须有哪种 Feature 或 Capability。The ID specifies which Feature or capability is required. 如果 TypeFeatureID 为 Feature 的 GUID,不仅用括号括住,还用连字符相连;例如:{151D22D9-95A8-4904-A0A3-22E4DB85D1E0}If Type is Feature, the ID is the bracketed, hyphenated GUID of the Feature; for example {151D22D9-95A8-4904-A0A3-22E4DB85D1E0}. 如果 TypeCapabilityID 为 Capability 的 GUID。If Type is Capability, the ID is the GUID of the capability. 下面列出了 Capability。The capabilities are listed below. 若要查找 Capability 的 GUID,请参阅 AppPrerequisite 元素 (AppPrerequisiteCollection complexType)(SharePoint 加载项清单)To get the find the GUID of a capability, see AppPrerequisite element (AppPrerequisiteCollection complexType) (SharePoint Add-in Manifest).

  • Access Services 2010Access Services 2010
  • Access ServicesAccess Services
  • Managed Metadata Web ServiceManaged Metadata Web Service
  • PowerPoint ServicesPowerPoint Services
  • Secure Store ServicesSecure Store Services
  • 机器翻译服务Machine Translation Service
  • User Profile ServiceUser Profile Service
  • Visio Graphics ServiceVisio Graphics Service
  • 工作管理服务Work Management Service
  • DuetDuet
  • 工作流Workflow
  • 搜索Search

下面是注册工作流功能的原始 AppPrerequisites 标记的示例。如果您使用的是 Visual Studio,可在设计器工具中编辑加载项清单。The following is an example of raw AppPrerequisites markup that registers the Workflow capability. If you are using Visual Studio, you edit the add-in manifest in a designer tool.

  <AppPrerequisite Type="Capability" ID="{CDD8F991-B459-4512-8048-03D5A03FF27E}" MinimumVersion="" />
</ AppPrerequisites>

本节内容In this section

另请参阅See also