浏览应用部件清单 (manifest) 结构和 SharePoint 加载项包

  • 项目

SharePoint 加载项包结构

SharePoint 加载项包是扩展名为“.app”且符合开放打包约定 (OPC) 的文件。 此包包含以下各项：

  • 加载项清单：这是名为 appmanifest.xml 的必需的文件。 它会告诉 SharePoint 有关加载项的一些重要属性，例如其标题和运行所需的权限。 有关此文件内容的详细信息，请参阅 SharePoint 加载项清单文件。

  • SharePoint 解决方案包：加载项可能视情况包含一个 SharePoint 解决方案包（.wsp 文件），其中包含加载项 Web 的组件。 这些组件可能包含页、列表实例、视图、文档、Web 范围的功能和其他 SharePoint 组件。 (有关 SharePoint 外接程序中可包含哪些 SharePoint 组件的详细信息，请参阅 SharePoint 外接程序中可包含的 SharePoint 组件类型。) .wsp 文件可能还包含 Office 外接程序。.wsp 文件中的组件将部署到外接程序 Web。 有关包含 SharePoint 解决方案包的加载项包的示例，请参阅创建包括自定义 SharePoint 列表和内容类型的提供程序托管的加载项。

  • 包含自定义操作或加载项部件的主机 Web 功能：除了部署到加载项 Web 的 SharePoint 组件之外，SharePoint 加载项还可将一个或多个自定义操作（快捷菜单项或功能区扩展）部署到主机 Web。 这通过以下方式实现：将位于包的 .wsp 文件之外和部署将转到主机 Web 的组件的功能包含在加载项包中。 此“稀疏”功能称为主机 Web 功能。

    外接程序部件以相同的方式部署到主机 Web。 主机 Web 功能由标准 SharePoint feature.xml文件和一个或多个关联的elements.xml文件组成。 例如，自定义操作的elements.xml文件包含自定义操作的 CustomAction 标记。 它还可以包含加载项部件的标记。 主机 Web 功能中只能包含这两种类型的组件。 这些主机 Web 功能未在外接程序清单中逐项列出。 但是，它们是 OPC 意义上的“部件”，加载项清单与其中每个文件之间存在显式 OPC 关系。 有关包含主机 Web 功能的外接程序包的示例，请参阅 创建使用 SharePoint 外接程序部署的自定义操作。

    注意

    租户管理员可选择将 SharePoint 加载项批安装到多个网站。 已通过此方式安装的加载项的范围可能为租户。 如果未批量安装此加载项，而是安装到各个单独的网站，则加载项可能为 Web 范围。 如果主机 Web 功能包含功能区扩展或加载项部件，则不会在批量安装加载项时将其部署到主机 Web，以便仅为快捷菜单项部署租户范围的加载项。

    不得混淆加载项范围和功能范围。 功能范围决定了功能元素的部署位置。 可能的位置包括场、Web 应用程序、网站（即网站集）和 Web。 对于 SharePoint 加载项中的功能（主机 Web 功能和加载项包中 .wsp 内的功能），只能使用 Web 选项。

    加载项范围是指在其中安装加载项的范围。 可能的位置为 Web（其中已将加载项点对点安装到一个或多个网站）和租户（其中已将加载项批量安装到客户租赁的网站的所有或部分子集）。

    有关租户和 Web 范围的详细信息，请参阅 SharePoint 加载项的租赁和部署范围。

  • 本地化资源文件 (.resx)：这些文件适用于本地化包含加载项标题的加载项清单的各个方面和加载项包中的主机 Web 功能的各个方面。 （位于其自己的包内的加载项包的各个部分，如 .wsp 文件、Azure 网站包和加载项清单，其中每个都有自己的本地化过程，这些过程将在相关项不是 SharePoint 加载项的一部分时完全应用。）有关包含 .resx 文件的主机 Web 功能的加载项包的示例，请参阅本地化 SharePoint 加载项。

  • Office 加载项清单：可能视情况存在一个或多个 Office 加载项清单，其中每个包对应一个 Office 加载项。 只有在加载项将被上传到 SharePoint 企业加载项目录（而不是公共市场）时，才会将此部分包含在加载项包中。 有关详细信息，请参阅发布 SharePoint 加载项。

SharePoint 加载项清单文件

每个 SharePoint 外接程序都包含一个 appmanifest.xml 文件。 appmanifest.xml 告知 SharePoint 其必须知道的有关外接程序的内容并且定义外接程序最重要的属性。 以下是在清单中指定的一些项：

  • 外接程序的内部名称、产品 ID 和版本。

  • 起始页的 URL，该页是在启动外接程序时打开的页。 这可以是外接程序 Web 中的页、基于云的页或 ISV 的 Web 服务器上的页。

    注意

    在某些情况下，可能会限制可在 StartPage 元素中指定的文件类型。 有关详细信息，请参阅 StartPage 元素 (PropertiesDefinition complexType)（SharePoint 加载项清单）。 将多个查询参数组合到 StartPage 值中时，必须使用编码的与号“&”而不是“&”或分号将其追加在一起。

  • 外接程序的其他属性。 这些属性包括标题和外接程序支持的区域设置（这二者是必需的）、处理安装后、升级后和卸载前事件的服务的 URL 以及创建外接程序 Web 时要使用的 Web 模板。

  • 外接程序对外接程序 Web 之外的 SharePoint 资源所需权限的请求。

  • 标识，供外接程序主体的身份验证和授权之用。 它是被授予权限的主体。 Sharepoint 托管的外接程序无需此标识。

  • 必须可供加载项使用才能安装加载项的必备项（如果有）的列表。 例如，可能需要安装并激活某些功能，并且可能需要许可并安装某些服务。

注意

外接程序清单文件是外接程序包中唯一必需的项，但之前列表中的项并不都是文件的必需部分。

有关加载项清单标记的详细信息，请参阅 SharePoint 加载项清单的架构参考。本主题不是该节点中信息的替代信息，该节点包括有关必需元素和属性的信息。 另请注意，SharePoint 加载项清单具有不同于 Office 加载项清单的架构。 可以在 Office 加载项清单的架构参考 (v1.1) 中查找有关后者的信息。

以下是 appmanifest.xml 文件的示例。 请注意，在本示例中，加载项的起始页是位于远程服务器上的 ASP.NET 页，而不是 SharePoint 网站上的页。 此页的 URL 包含一个查询字符串，它将主机 Web 的 URL 传递到远程 Web 应用程序。 该字符串的 {HostUrl} 部分是启动加载项时解析的标记。 加载项将请求对主机 Web 中所有列表的写入权限。 必须为其授予此权限的加载项主体是远程 Web 应用程序。

必须在加载项清单中使用 SupportedLocales 或 SupportedLanguages 元素。 将弃用 SupportedLanguages 并使用 SupportedLocales。 在发布后，SupportedLanguages 元素可能仍继续可用，但请勿使用它。 有关这些元素的详细信息，请参阅 SupportedLocales 元素 (PropertiesDefinition complexType)（SharePoint 加载项清单）和 SupportedLanguages 元素 (PropertiesDefinition complexType)（SharePoint 加载项清单）。

注意

AppPermissionRequest 元素的 Scope 属性的值的结构类似 URI，但它们实际上是文本字符串。 以下示例中的示例 Scope 值中没有任何部分是占位符。 有关权限的详细信息，请参阅 SharePoint 中的加载项权限。

<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0"
     Name="MySampleApp"
>
  <Properties>
    <Title>My Sample App</Title>
    <StartPage>http://MyRemoteWebApplicationServer/default.aspx/?SPHostUrl={HostUrl}</StartPage>
    <SupportedLocales>
      <SupportedLocale CultureName="en-US" />
    </SupportedLocales>        
  </Properties>

  <AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write"/>
  </AppPermissionRequests>

  <AppPrincipal>
    <RemoteWebApplication ClientId="1ee82b34-7c1b-471b-b27e-ff272accd564" />
  </AppPrincipal>
</App>

加载项清单中的 URL 标记

SharePoint 提供了多个令牌，这些令牌可用于 StartPage 元素和外接程序和加载项组件中的其他位置，以表示在加载项运行之前未知的信息。 SharePoint 基础结构将解析这些标记。 部分标记用于 URL 的开头，其他标记可在 URL 中使用，如查询参数的值。 这些标记和若干其他标记还可在各种 SharePoint 开发上下文中使用。

有关所有标记以及可使用它们的位置的详细信息，请参阅 SharePoint 加载项中的 URL 字符串和标记。有关 SharePoint 中的其他标记和 URL 的常规信息，请参阅 SharePoint 中的 URL 和标记。

注意

这些标记不会在 AppPermissionRequest 元素的 Scope 属性中使用。

另请参阅