创建Outlook日历会议时校验JIRA编号的开发与排障求助

云原生阿岚

2026-6-12

Outlook插件安装失败排查与修复（会议邀请JIRA编号校验功能）

要开发一款Outlook插件，实现创建会议邀请时校验主题或正文中是否包含有效JIRA编号（格式如DK-####）。但编写manifest文件后，安装时提示“Outlook插件安装失败”。以下是原manifest文件和function-file.js代码：

原Manifest文件

<?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:ov="http://schemas.microsoft.com/office/mailappversionoverrides"
           xsi:type="MailApp">

  <Id>f5f2c3a0-7c2a-4c39-9fd5-5c4f2f6b8d10</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Your Company</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Jira Key Check (On Send)"/>
  <Description DefaultValue="Blocks sending if no DK-#### Jira key is found in subject or body."/>

  <!-- Icons + Support -->
  <IconUrl DefaultValue="https://25463d76d287.ngrok-free.app/assets/icon-64.png"/>
  <HighResolutionIconUrl DefaultValue="https://25463d76d287.ngrok-free.app/assets/icon-128.png"/>
  <SupportUrl DefaultValue="https://25463d76d287.ngrok-free.app/support.html"/>

  <Hosts>
    <Host Name="Mailbox"/>
  </Hosts>

  <Requirements>
    <Sets>
      <Set Name="Mailbox" MinVersion="1.8"/>
    </Sets>
  </Requirements>

  <!-- Base schema requires FormSettings; keep minimal + valid -->
  <FormSettings>
    <!-- READ form: NO RequestedHeight here -->
    <Form xsi:type="ItemRead">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://25463d76d287.ngrok-free.app/placeholder.html"/>
      </DesktopSettings>
    </Form>
    <!-- EDIT form: RequestedHeight IS allowed/expected -->
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://25463d76d287.ngrok-free.app/placeholder.html"/>
        <RequestedHeight>250</RequestedHeight>
      </DesktopSettings>
    </Form>
  </FormSettings>

  <Permissions>ReadWriteItem</Permissions>

  <!-- Minimal rules so the base schema is happy -->
  <Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
    <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit"/>
  </Rule>

  <!-- Use the CORRECT namespace for mail add-ins -->
  <ov:VersionOverrides Version="1.0">
    <ov:Hosts>
      <ov:Host xsi:type="ov:MailHost">
        <ov:ExtensionPoint xsi:type="ov:Events">
          <ov:Event Type="ItemSend" FunctionName="validateOnSend"/>
        </ov:ExtensionPoint>
      </ov:Host>
    </ov:Hosts>

    <ov:Resources>
      <bt:Urls>
        <bt:Url id="functionFileUrl" DefaultValue="https://25463d76d287.ngrok-free.app/function-file.html"/>
      </bt:Urls>
    </ov:Resources>

    <ov:FunctionFile resid="functionFileUrl"/>
  </ov:VersionOverrides>
</OfficeApp>

原function-file.js代码

Office.onReady(() => { });

async function validateOnSend(event) {
    try {
        const item = Office.context.mailbox.item;
        const subject = await getSubject(item);
        const bodyText = await getBodyText(item);
        const jiraRegex = /\bDK-\d+\b/i;
        const hasJira = jiraRegex.test(subject) || jiraRegex.test(bodyText);

        if (!hasJira) {
            item.notificationMessages.addAsync("missingJira", {
                type: "errorMessage",
                message: "Add a Jira key (e.g., DK-1234) in subject or body before sending."
            });
            event.completed({ allowEvent: false });
            return;
        }

        event.completed({ allowEvent: true });
    } catch (err) {
        item.notificationMessages.addAsync("jiraError", {
            type: "errorMessage",
            message: "Could not validate Jira key. Please check manually."
        });
        event.completed({ allowEvent: false });
    }
}

function getSubject(item) {
    return new Promise((resolve, reject) => {
        item.subject.getAsync(result =>
            result.status === Office.AsyncResultStatus.Succeeded
                ? resolve(result.value || "")
                : reject(result.error)
        );
    });
}

function getBodyText(item) {
    return new Promise((resolve, reject) => {
        item.body.getAsync(Office.CoercionType.Text, result =>
            result.status === Office.AsyncResultStatus.Succeeded
                ? resolve(result.value || "")
                : reject(result.error)
        );
    });
}

Office.actions.associate("validateOnSend", validateOnSend);

问题根源与修复方案

原manifest文件存在3个不符合Office插件规范的问题，导致安装失败：

1. VersionOverrides命名空间版本过低

使用的ov命名空间指向旧版http://schemas.microsoft.com/office/mailappversionoverrides，需要更新为v1.1版本的规范地址，并明确版本类型。

2. 事件声明结构错误

ItemSend事件的声明应使用ov:EventHandlers节点，而非旧版的ov:ExtensionPoint结构。

3. 冗余FormSettings配置

仅使用后台事件的插件无需保留ItemRead表单配置，多余的配置可能引发页面加载校验失败。

修正后的Manifest文件

<?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:ov="http://schemas.microsoft.com/office/mailappversionoverrides/1.1"
           xsi:type="MailApp">

  <Id>f5f2c3a0-7c2a-4c39-9fd5-5c4f2f6b8d10</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Your Company</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Jira Key Check (On Send)"/>
  <Description DefaultValue="Blocks sending if no DK-#### Jira key is found in subject or body."/>

  <IconUrl DefaultValue="https://25463d76d287.ngrok-free.app/assets/icon-64.png"/>
  <HighResolutionIconUrl DefaultValue="https://25463d76d287.ngrok-free.app/assets/icon-128.png"/>
  <SupportUrl DefaultValue="https://25463d76d287.ngrok-free.app/support.html"/>

  <Hosts>
    <Host Name="Mailbox"/>
  </Hosts>

  <Requirements>
    <Sets>
      <Set Name="Mailbox" MinVersion="1.8"/>
    </Sets>
  </Requirements>

  <!-- 简化FormSettings，仅保留必要的编辑表单配置 -->
  <FormSettings>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <SourceLocation DefaultValue="https://25463d76d287.ngrok-free.app/placeholder.html"/>
      </DesktopSettings>
    </Form>
  </FormSettings>

  <Permissions>ReadWriteItem</Permissions>

  <Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
    <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit"/>
  </Rule>

  <!-- 使用v1.1版本的VersionOverrides规范 -->
  <ov:VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <ov:Requirements>
      <ov:Sets DefaultMinVersion="1.8">
        <ov:Set Name="Mailbox"/>
      </ov:Sets>
    </ov:Requirements>
    <ov:Hosts>
      <ov:Host xsi:type="MailHost">
        <ov:EventHandlers>
          <ov:EventHandler Type="ItemSend" FunctionName="validateOnSend"/>
        </ov:EventHandlers>
      </ov:Host>
    </ov:Hosts>
    <ov:Resources>
      <bt:Urls>
        <bt:Url id="functionFileUrl" DefaultValue="https://25463d76d287.ngrok-free.app/function-file.html"/>
      </bt:Urls>
    </ov:Resources>
    <ov:FunctionFile resid="functionFileUrl"/>
  </ov:VersionOverrides>
</OfficeApp>

关键修改说明

更新ov命名空间为http://schemas.microsoft.com/office/mailappversionoverrides/1.1，并添加xsi:type="VersionOverridesV1_1"标识版本类型
将事件声明从ov:ExtensionPoint改为ov:EventHandlers结构，符合最新的插件事件规范
移除ItemRead表单配置，简化FormSettings，避免不必要的页面校验问题
添加ov:Requirements节点，明确插件依赖的Mailbox最低版本，增强兼容性

前端页面验证

确保function-file.html正确引入Office.js和脚本文件，示例代码如下：

<!DOCTYPE html>
<html>
<head>
    <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
    <script src="function-file.js"></script>
</head>
<body></body>
</html>

内容的提问来源于stack exchange，提问作者Praveen

创建Outlook日历会议时校验JIRA编号的开发与排障求助

原Manifest文件 #

原function-file.js代码 #

问题根源与修复方案 #

1. VersionOverrides命名空间版本过低 #

2. 事件声明结构错误 #

3. 冗余FormSettings配置 #

修正后的Manifest文件 #

关键修改说明 #

前端页面验证 #