在 Office 加载项清单中，为什么 <Permissions> 必须紧跟 <FormSettings/>？答案

【问题标题】：In an Office add-in manifest, why must <Permissions> immediately follow <FormSettings/>?在 Office 加载项清单中，为什么 <Permissions> 必须紧跟 <FormSettings/>？
【发布时间】：2017-05-26 05:28:29
【问题描述】：

这个问题最好通过例子来说明。考虑以下几点：

在第一个示例中，我的 <Permissions/> 元素紧跟在 <FormSettings/> 块之后：

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:mailappor="http://schemas.microsoft.com/office/mailappversionoverrides/1.0" xsi:type="MailApp">
  <Id>464672b2-35a8-44a1-8c06-3ad07ed893a7</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Example</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Example A"/>
  <Description DefaultValue="This is an example add-in."/>
  <IconUrl DefaultValue="https://placehold.it/64x64"/>
  <HighResolutionIconUrl DefaultValue="https://placehold.it/64x64"/>
  <SupportUrl DefaultValue="https://example.com/"/>
  <Hosts>
    <Host Name="Mailbox"/>
  </Hosts>
  <Requirements>
    <Sets>
      <Set Name="MailBox" MinVersion="1.1"/>
    </Sets>
  </Requirements>
  <FormSettings>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://example.com"/>
      </DesktopSettings>
    </Form>
  </FormSettings>
  <Permissions>ReadWriteMailbox</Permissions>
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
  </Rule>
</OfficeApp>

我能够成功将此清单添加到我的 Exchange 管理中心的组织加载项列表中。

但是，如果我将 <Permissions/> 元素移动到清单中其他任何地方，则清单在尝试添加时验证失败：

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:mailappor="http://schemas.microsoft.com/office/mailappversionoverrides/1.0" xsi:type="MailApp">
  <Id>464672b2-35a8-44a1-8c06-3ad07ed893a7</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Example</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Example A"/>
  <Description DefaultValue="This is an example add-in."/>
  <IconUrl DefaultValue="https://placehold.it/64x64"/>
  <HighResolutionIconUrl DefaultValue="https://placehold.it/64x64"/>
  <SupportUrl DefaultValue="https://example.com/"/>
  <Hosts>
    <Host Name="Mailbox"/>
  </Hosts>
  <Requirements>
    <Sets>
      <Set Name="MailBox" MinVersion="1.1"/>
    </Sets>
  </Requirements>
  <FormSettings>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://example.com"/>
      </DesktopSettings>
    </Form>
  </FormSettings>
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
  </Rule>
  <Permissions>ReadWriteMailbox</Permissions>
</OfficeApp>

尝试将此清单添加到我的 Exchange 管理中心的组织加载项列表会产生以下错误：

无法安装此应用。清单文件不符合架构定义。命名空间“http://schemas.microsoft.com/office/appforoffice/1.1”中的元素“OfficeApp”在命名空间“http://schemas.microsoft.com/office/appforoffice/1.1”中具有无效的子元素“权限”。预期的可能元素列表：命名空间“http://schemas.microsoft.com/office/appforoffice/1.1”中的“DisableEntityHighlighting”以及命名空间“http://schemas.microsoft.com/office/mailappversionoverrides”中的“VersionOverrides”以及命名空间“http://www.w3.org/2000/09/xmldsig#”中的任何元素...

只有通过反复试验，我们才能找到验证失败的根本原因。

我的问题：为什么排序很重要？为什么<Permissions/> 元素不能出现在清单中同一嵌套级别的任何位置？

上下文

此验证失败发生在托管 Exchange (Office 365) 中，以及在请求清单的步骤尝试向 Office 商店提交加载项时。

【问题讨论】：

标签： outlook ms-office office-js office-addins

【解决方案1】：

为什么排序很重要？

模式文件定义的标签顺序。在您的情况下，您已包含在清单 http://schemas.microsoft.com/office/appforoffice/1.1 Schema 中。尝试在架构<Permissions/> 元素中查找，您将看到以下定义...

<xs:complexType name="MailApp">
 <xs:complexContent>
   <xs:extension base="OfficeApp">
     <xs:sequence>
       <xs:element name="Requirements" type="MailAppRequirements" minOccurs="1" maxOccurs="1"/>
       <xs:element name="FormSettings" type="FormSettings" minOccurs="1" maxOccurs="1"/>
       <xs:element name="Permissions" minOccurs="0" maxOccurs="1" type="ST_Permissions2"/>
       <xs:element name="Rule" type="Rule" minOccurs="1" maxOccurs="1"/>
       <xs:element name="DisableEntityHighlighting" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
       <xs:element ref="mailor:VersionOverrides" minOccurs="0" maxOccurs="1"/>
       <xs:any id="MailAppSignature" minOccurs="0" maxOccurs="1" namespace="http://www.w3.org/2000/09/xmldsig#" processContents="lax"/>
     </xs:sequence>
   </xs:extension>
 </xs:complexContent>

元素 <Permissions/> 在 <sequence/> 中，这意味着它必须按此元素定义的顺序，并且它就在 <FormSettings/> 之后，没有其他地方。

【讨论】：

谢谢，斯拉瓦！这回答了验证失败的技术原因，这是值得接受的答案。字里行间还有一个问题：为什么将其定义为特定序列而不是无序集？
@DevinCanterberry "为什么将其定义为特定序列而不是无序集？" -- 这将是 Microsoft Office API 开发团队的问题。我们是此 API 的用户，只需遵循他们为我们创建的架构和设计；）

【解决方案2】：

模式文件定义的标签顺序。不幸的是，这没有很好的记录，我们正在努力改进这个文档。由于我们验证安装架构的方式，在为 Outlook Web 加载项定义清单时，顺序很重要。我们意识到这可能很麻烦尤其是，因为它没有很好的文档记录，但我们需要特定订单的主要原因是因为它允许我们快速验证清单内容并提高服务性能。

感谢您对我们的文档提供反馈。

Outlook Web 插件团队

【讨论】：

有关清单的一些文档，请查看我们的示例here