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-cache
This package can be used to clear the Office add-ins cache.
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
npm registry auth
Run the following command to get the authenticator for the first time:
npm install --global @microsoft/artifacts-npm-credprovider --registry https://pkgs.dev.azure.com/artifacts-public/23934c1b-a3b5-4b70-9dd3-d1bef4cc72a0/_packaging/AzureArtifacts/npm/registry/
Run artifacts-npm-credprovider to authenticate for the npm registry.
Getting started
In a command prompt, run:
This should also be done when after pulling additional changes or switching branches.
Build
To build all packages, at the root directory, run:
To build a single package, in the directory for the package, run:
Test
To run tests for all packages, at the root directory, run:
To run tests for a single package, in the directory for the package, run:
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
- Install Git, NodeJs and VS Code if you haven’t ready.
- Create a GitHub account if you don’t already have one.
- Go to https://github.com/OfficeDev/Office-Addin-Scripts
- Create a fork of OfficeDev/Office-Addin-Scripts in GitHub
- In a command prompt:
git clone https://github.com/OfficeDev/Office-Addin-Scripts
cd Office-Addin-Scripts
git remote add {username} https://github.com/{username}/Office-Addin-Scripts.git (where “{username}” is your GitHub user name)
git checkout -b my-branch-name (recommend using all lowercase with hyphens for branch names)
- Make your desired changes
- Commit your changes and push the fork you created
- git commit
- git push -u {username} {branch-name}
- Go to Office-Addin-Scripts and create a pull request.
Feedback
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