officedev/office-ooxml-embedaddin

Web application that uses Open XML SDK to configure Office documents to automatically open a specified add-in.

page_type	products	languages	extensions
sample	office-365	csharp	contentType createdDate samples 6/13/2017 10:42:04 AM

Web application that uses Open XML SDK to configure Office documents to automatically open a specified add-in

The are a number of scenarios in which an Office Add-in should be embedded in an Office document and automatically open when the document opens.

Note: For more information about automatically opening an add-in in a document, see Automatically open a task pane with a document.

This sample uses .NET and the Open XML SDK to configure Office documents with the markup that makes this possible. In this sample, the Script Lab add-in is embedded in an Office file of the user's choice.

Table of Contents

• Change History
• Prerequisites
• To use the project
• About the code
• Questions and comments
• Additional resources

Change History

June 15, 2017:

• Initial version.

July 8, 2020

• Fixed old links.

Prerequisites

• Office 2016, Version 1705, build 16.0.8122.1000 Click-to-Run, or later.
• Visual Studio 2017 or later.
• Open XML SDK 2.5
• The add-in that is embedded, which is Script Lab in the case of this sample, must have markup that enables auto-open in its manifest. For more details see Automatically open a task pane with a document.

To use the project

1. Clone or download this repo.

2. Open the Office-OOXML-EmbedAddin.sln file in Visual Studio.

3. In Visual Studio add references to these assemblies:

   • WindowsBase (in the Framework tab of the Visual Studio Extensions Manager)
   • DocumentFormat.OpenXml (in the Extensions tab)

4. Right-click the project name in Solution Explorer and select Properties.

5. When the Properties pane opens, open the Web tab.

6. On the Web tab, enable Specific Page and enter home.aspx in the text box.

7. Press F5. This opens the home page of the application in your browser.

8. Use the Browse control on the page to navigate to any Excel, Word, or PowerPoint file.

9. Press Upload.

10. Optional. If there is a particular snippet that you want to import as soon as Script Lab runs, enter its Gist ID in the textbox.

Note: This feature may not be supported in Script Lab for a short period after this sample is released. But it will do no harm to enter a Gist ID.

8. Press Embed Script Lab.
9. Press Download and follow your browser's prompts to open or save the file. When the file opens, the task pane opens and near the top, you are prompted to trust Script Lab (unless you already had it installed). When you do, Script Lab opens.
10. To verify that Script Lab is embedded in the document, close the file and reopen it. Script Lab opens in the task pane immediately.

About the code

The file Home.aspx.cs:

• Provides the button event handlers and basic UI manipulation.
• Uses standard ASP.NET techniques to upload and download the file.
• Uses the file name extension of the uploaded file (xlsx, docx, or pptx) to determine the type of file. This needs to be done at the outset because the Open XML SDK generally has distinct APIs for each type of file.
• Calls into the OOXMLHelper to validate the file and calls into the AddInEmbedder to embed Script Lab in the file and set to automatically open.

The file AddInEmbedder.cs:

• Provides the main business logic, which in this sample is a method that embeds Script Lab.
• It makes calls into the OOXML helper based on the type of the file.

The file OOXMLHelper.cs:

• Provides all the detailed OOXML manipulation.
• Uses a standard technique for validating the Office file, which is simply to call the *Document.Open method on it. If the file is invalid, the method throws an exception.
• Contains mainly code that was generated by the Open XML 2.5 SDK Productivity Tools which are available at the link for the Open XML 2.5 SDK above.

There are two critical lines in this file.

First, is the line in the GenerateWebExtensionPart1Content method that sets the reference to Script Lab (strictly speaking, to the manifest for Script Lab):

We.WebExtensionStoreReference webExtensionStoreReference1 = new We.WebExtensionStoreReference() { Id = "wa104380862", Version = "1.1.0.0", Store = "en-US", StoreType = "OMEX" };

In this code:

• The StoreType value is "OMEX", an alias for the Office Store.
• The Store value is "en-US" the culture section of the store where Script Lab is.
• The Id value is the Office Store's asset ID for Script Lab.

If you were setting up an add-in from a file share catalog for auto-open, you would use different values:

• The StoreType value would be "FileSystem".
• The Store value would be the URL of the network share; for example, "\\MyComputer\MySharedFolder". This should be the exact URL that appears as the share's Trusted Catalog Address in the Office Trust Center.
• The Id value would be the app ID in the add-ins manifest.

Note: For more information about alternative values for these attributes, see Automatically open a task pane with a document.

Second, is the line in the GeneratePartContent method that specifies the visibility of the taskpane when the file opens.

Wetp.WebExtensionTaskpane webExtensionTaskpane1 = new Wetp.WebExtensionTaskpane() { DockState = "right", Visibility = true, Width = 350D, Row = (UInt32Value)4U };

In this code, the Visibility property of the WebExtensionTaskpane object is set to true. The effect of this is that the very first time that the file is opened after the code is run, the task pane opens with Script Lab in it (after the user accepts the prompt to trust Script Lab). This is what we want for this sample. However, in most scenarios you will probably want this set to false. The effect of setting it to false is that the first time the file is opened, the user has to install the add-in, from the Add-in button on the ribbon. On every subsequent opening of the file, the taskpane with the add-in opens automatically.

The advantage of setting this property to false is that you can use the Office.js to turn give users the ability to turn on and off the auto-opening of the add-in. Specifically, your script sets the Office.AutoShowTaskpaneWithDocument document setting to true or false. However, if WebExtensionTaskpane.Visibility is set to true, there is no way for Office.js or, hence, your users to turn off the auto-opening of the add-in. Only editing the OOXML of the document can change WebExtensionTaskpane.Visibility to false.

Note: For more information about task pane visibility at the level of the Open XML that these .NET APIs represent, see Automatically open a task pane with a document.

Questions and comments

We'd love to get your feedback about this sample. You can send your feedback to us in the Issues section of this repository.

Questions about Microsoft Office 365 development in general should be posted to Stack Overflow. If your question is about the Office JavaScript APIs, make sure that your questions are tagged with [office-js].

Additional resources

• Office add-in documentation
• Office Dev Center
• More Office Add-in samples at OfficeDev on Github
• Script Lab

Copyright

Copyright (c) 2017, 2020 Microsoft Corporation. All rights reserved.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

office-ooxml-embedaddin's Issues

Auto taskpane open feature not working on MAC

Hello,
I want to open taskpane automatically after opening a document. I followed https://docs.microsoft.com/en-us/office/dev/add-ins/develop/automatically-open-a-task-pane-with-a-document this link.
According to link, I have configured WebExtension in document OOXML like below

        TaskPane taskPane = new TaskPane();
        document.WebExtensionTaskPanes.Add(taskPane);
        taskPane.DockState = TaskPaneDockState.Right;
        taskPane.IsVisible = true;
        taskPane.Width = 300;
        taskPane.WebExtension.Id = "09c70a19-bd78-4fc4-a183-30d856b6e48c";
        taskPane.WebExtension.Reference.Id = "09c70a19-bd78-4fc4-a183-30d856b6e48c";
        taskPane.WebExtension.Reference.Version = "1.0.0.0";
        taskPane.WebExtension.Reference.StoreType = "ExCatalog";
        taskPane.WebExtension.Reference.Store = "EXCatalog";
        
        taskPane.WebExtension.Properties.Add(new WebExtensionProperty("Office.AutoShowTaskpaneWithDocument", "true"));

I have deployed my addin on Centralized Deployment using Micrsoft 365 admin center .

Auto taskpane open feature works perfect on Windows. When we open document on Windows taskpane with ID 09c70a19-bd78-4fc4-a183-30d856b6e48c open automatically. But when we open the same document on MAC, it opens the empty taskpane. Its not loading the provided application in taskpane. Also not showing any error.

Will anybody please help me to find the cause?

Error after click "Embed Script Lab"

Error Describtion:

I followed step to embed add-in in excel file, and after click "Embed Script Lab" button,
I encount the following error:
(I changed the code only to let it print detail exception tracestack)

ERROR: DocumentFormat.OpenXml.Packaging.OpenXmlPackageException: Only one instance of the type is allowed for this parent. 
在 DocumentFormat.OpenXml.Packaging.OpenXmlPartContainer.InitPart[T](T newPart, String contentType, String id) 
在 DocumentFormat.OpenXml.Packaging.OpenXmlPartContainer.InitPart[T](T newPart, String contentType) 
在 DocumentFormat.OpenXml.Packaging.SpreadsheetDocument.AddWebExTaskpanesPart() 
在 Office_OOXML_EmbedAddin.AddinEmbedder.EmbedAddin(String fileType, MemoryStream memoryStream, String snippetID) 
位置 C:\Users\Morri\Documents\NodeProjects\Office-OOXML-EmbedAddin\Office-OOXML-EmbedAddin\AddinEmbedder.cs:行号 22 
在 Office_OOXML_EmbedAddin.WebForm1.btnEmbed_Click(Object sender, EventArgs e) 
位置 C:\Users\Morri\Documents\NodeProjects\Office-OOXML-EmbedAddin\Office-OOXML-EmbedAddin\Home.aspx.cs:行号 86

I have tried some .xlsx files but get the same error

Environment:

system: windows 10
Microsoft Excel: 2016 MSO (16.0.11901.20070)
visual studio 2019

.

Could any one help me with this problem? Thanks very much!

Cannot find `Upload` to press

Hello,

I'm trying to run this project on my machine. I just added a test.xlsx in the folder, and pressing F5 opened a browser as follows:

From the readme, I should Use the Browse control on the page to navigate to any Excel, Word, or PowerPoint file and Press Upload, but where is Upload?

Could anyone help?

Cheers

Tie

Use Open XML to Auto Open and Excel Task Pane Add-in

Hi @Rick-Kirkham

We are seeking to Auto Open an Task Pane Add-in required in an Excel Workbook for users who do not have the Task Pane Add-in installed. The Add-in is published in AppSource.

We understand from Use Open XML to tag the document that to do this, webextension and taskpane parts have to be added to the workbook to set visibility=1 and add other references.

Ideally, we would like to add/set these parts when the Add-in is used so that when the Workbook is saved and sent to another "Add-in not installed user", they would be prompted to Trust the Add-in, it will be installed, enabled for the workbook and (we assume) added to their My Add-ins list.

Some hurdles we have discovered/expect:

1. There is no equivalent OoxmlCoercion method for Excel (Word only)?
2. You cannot write these two parts to an open Workbook Open XML with the approach of the C# code in this repo?
3. How can we implement a solution using JavaScript and/or the Excel JS API

Can you please comment on the above, and provide any advice for our use case and requirements.

Thanks for your help.
David

cc @sanjeet-pm