Office-Addin-Scripts

These packages provide functionality which can be used to perform tasks related to Office Add-ins. The packages export functions which can be imported and used in Node scripts. Many of the packages also provide a command-line interface (CLI), allowing them to be used directly from a Command Prompt / Terminal window.

The Yo Office templates provide a starting point for developing an Office Add-in. These scripts are used in the templates to provide for basic developer tasks such as debugging.

Developers may have other workflows with different requirements and tooling. Our goal is for the these packages to serve as building blocks which can be adapted as needed. We encourage feedback and contributions from the community.

The Excel Custom Functions project provides an example of how these packages may be used.

In this repository

• custom-functions-metadata

  This package allows metadata for custom functions to be generated automatically from JSDoc tags and the function parameter types.

• custom-functions-metadata-plugin

  A WebPack plugin which generates the metadata for custom functions.

• office-addin-cli

  A command-line interface for Office Add-ins.

• office-addin-debugging

  This package provides the orchestration of components related to debugging Office Add-ins. When debugging is started, it will ensure that the dev-server is running, that dev settings are configured for debugging, and will register and sideload the Office Add-in. When debugging is stopped, it will unregister and shutdown components.

• office-addin-dev-certs

  This package can be used to manage certificates for development server using https://localhost.

• office-addin-dev-settings

  This package can be used to configure developer settings for an Office Add-in.

• office-addin-lint

  This package can be used to ensure code quality with lint rules and standardize code formatting.

• office-addin-manifest

  This package provides the ability to parse, display, and modify the manifest file for Office Add-ins.

• office-addin-mock

  This package provides a way to unit test the Office JavaScript API.

• office-addin-node-debugger

  This package allows a Node instance to serve as a proxy for debugging a JavaScript runtime hosted by an Office application.

• office-addin-project

  This package provides the ability to do project wide commands for Office Add-ins, such as conversion.

• office-addin-sso

  This package provides the ability to register an application in Azure Active Directory and infrastructure for implementing single sign-on (SSO) taskpane add-ins.

• office-addin-test-helpers

  This package provides tools that make validating your Office Add-in easier. You can use it with the office-addin-test-server package and the Mocha test framework (or another testing framework of your choice).

• office-addin-test-server

  This package provides a framework for testing Office task pane add-ins by allowing add-ins to send results to a test server. The results can then be consumed and used by tests to validate that the add-in is working as expected.

• office-addin-usage-data

  This package allows for sending usage data event and exception data to the selected telemetry infrastructure (e.g. ApplicationInsights)

Requirements

• Node.js

Getting started

In a command prompt, run:

• npm install

This should also be done when after pulling additional changes or switching branches.

Build

To build all packages, at the root directory, run:

• npm run build

To build a single package, in the directory for the package, run:

• npm run build

Test

To run tests for all packages, at the root directory, run:

• npm run test

To run tests for a single package, in the directory for the package, run:

• npm run test

Editing

Use VS Code to edit, build, test, and debug by opening the package folder in VS Code.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Quickstart with Git

1. Install Git, NodeJs and VS Code if you haven’t ready.
2. Create a GitHub account if you don’t already have one.
3. Go to https://github.com/OfficeDev/Office-Addin-Scripts
4. Create a fork of OfficeDev/Office-Addin-Scripts in GitHub
5. In a command prompt:
   1. git clone https://github.com/OfficeDev/Office-Addin-Scripts
   2. cd Office-Addin-Scripts
   3. git remote add {username} https://github.com/{username}/Office-Addin-Scripts.git (where “{username}” is your GitHub user name)
   4. git checkout -b my-branch-name (recommend using all lowercase with hyphens for branch names)
6. Make your desired changes
7. Commit your changes and push the fork you created
   1. git commit
   2. git push -u {username} {branch-name}
8. Go to Office-Addin-Scripts and create a pull request.

Feedback

• Ask a question on Stack Overflow.

• File an Issue.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

Join the Microsoft 365 Developer Program

Join the Microsoft 365 Developer Program to get resources and information to help you build solutions for the Microsoft 365 platform, including recommendations tailored to your areas of interest.

You might also qualify for a free developer subscription that's renewable for 90 days and comes configured with sample data; for details, see the FAQ.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

License

Code licensed under the MIT License.

Data usage

The Office Add-in CLI tools collect anonymized usage data and send it to Microsoft. This allows us to understand how the tools are used and how to improve them.

For more details on what we collect and how to turn it off, see our Data usage notice