如何使用.NET OpenXml库为Excel文档预配置Office 365外接程序

以下是经过生产环境验证的实现方案，完全兼容已上架AppSource的Excel外接程序预装需求：

前提准备 #

• 安装NuGet包：DocumentFormat.OpenXml（建议使用2.20.0及以上稳定版本，低版本对webextension扩展结构的API支持存在缺陷，是官方示例运行失败的常见原因）
• 提前备好外接程序核心参数：AppSource ID、上架版本号、外接程序显示名称、提供商名称、自定义启动参数（如有）

核心实现代码 #

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Office2013.WebExtension;
using DocumentFormat.OpenXml.Office2013.WebExtentionPane;

public static void EmbedAddinToExcel(string excelFilePath, string appSourceId, string addinDisplayName, string providerName)
{
    using (var document = SpreadsheetDocument.Open(excelFilePath, true))
    {
        // 创建WebExtension配置部分
        var webExtensionPart = document.WorkbookPart.AddNewPart<WebExtensionPart>();
        var webExtension = new WebExtension() { Id = webExtensionPart.GetIdOfPart(webExtensionPart) };
        
        // 配置外接程序标识（必填项，官方示例最容易写错的部分）
        webExtension.Reference = new WebExtensionReference()
        {
            Id = appSourceId,
            Version = "1.0.0.0", // 和你上架的外接程序版本号保持一致
            Store = appSourceId, // 已上架AppSource的外接程序直接填写AppSource ID
            StoreType = "OMEX" // 固定值，代表从Office应用商店加载外接程序
        };
        
        // 配置外接程序基础属性
        webExtension.Properties = new WebExtensionProperties();
        webExtension.Properties.Append(new WebExtensionProperty() { Name = "Name", Value = addinDisplayName });
        webExtension.Properties.Append(new WebExtensionProperty() { Name = "Provider", Value = providerName });
        // 如需外接程序打开文档时自动启动，添加下面的配置
        webExtension.Properties.Append(new WebExtensionProperty() { Name = "AutoOpen", Value = "true" });
        
        webExtension.OfficeAppVersion = "16.0"; // 兼容Office 2016及以上版本
        webExtensionPart.WebExtension = webExtension;
        
        // 绑定任务窗格默认配置
        var taskPanePart = document.WorkbookPart.AddNewPart<WebExtensionTaskPanesPart>();
        var taskPanes = new Taskpanes();
        var taskPane = new TaskPane()
        {
            DockState = "right", // 默认停靠在窗口右侧
            Visibility = true, // 默认显示任务窗格
            Width = 350, // 默认窗格宽度
            Row = 0
        };
        taskPane.WebExtensionReference = new WebExtensionPartReference() { Id = document.WorkbookPart.GetIdOfPart(webExtensionPart) };
        taskPanes.Append(taskPane);
        taskPanePart.Taskpanes = taskPanes;
        
        document.WorkbookPart.Workbook.Save();
    }
}

验证与同步 #

代码执行完成后先本地打开生成的Excel文档，确认外接程序可以正常加载、无报错后，再通过Graph API执行上传同步操作即可。

常见踩坑点 #

• 不要使用2.19版本以下的OpenXml SDK，旧版本存在WebExtension相关类的命名空间拼写错误，会导致写入的配置不被Office识别
• StoreType必须严格填写OMEX，仅企业内部部署的外接程序填EXCatalog，本地旁加载测试的外接程序填WopiCatalog
• 如需外接程序默认隐藏，可将TaskPane的Visibility属性设为false，用户可手动从外接程序菜单唤起
• 不要手动修改WebExtension的Id属性，必须使用OpenXmlPart生成的关联Id，否则会出现绑定失效问题

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