Exercise - Mail add-in basics

  • 7 minutes

In this exercise, you'll learn how to create your first Outlook add-in project and load it in the Outlook client.

Prerequisites

Developing Outlook add-ins require Outlook 2016 (or later) or Outlook on the web.

You'll use Node.js to create the custom Outlook add-in in this module. The exercises in this module assume you have the following tools installed on your developer workstation.

Important

In most cases, installing the latest version of the following tools is the best option. The versions listed here were used when this module was published and last tested.

You must have the minimum versions of these prerequisites installed on your workstation.

For this exercise, you'll also need a GitHub account.

Setup

The add-in that you'll create in this tutorial will read gists from the user's GitHub account and add the selected gist to the body of a message. Complete the following steps to create two new gists that you can use to test the add-in you're going to build.

  1. Sign in to GitHub.

  2. Create a new gist.

    • In the Gist description... field, enter Hello World Markdown.

    • In the Filename including extension... field, enter test.md.

    • Add the following markdown to the multiline textbox:

      # Hello World

This is content converted from Markdown!

Here's a JSON sample:

  ```json
  {
    "foo": "bar"
  }
  ```

    • Select the Create public gist button.

  3. Create another new gist.

    • In the Gist description... field, enter Hello World Html.

    • In the Filename including extension... field, enter test.html.

    • Add the following markdown to the multiline textbox:

      <html>
  <head>
    <style>
    h1 {
      font-family: Calibri;
    }
    </style>
  </head>
  <body>
    <h1>Hello World!</h1>
    <p>This is a test</p>
  </body>
</html>

    • Select the Create public gist button.

Create an Outlook add-in project

  1. Run the following command to create an add-in project using the Yeoman generator:

    yo office

    Note

    When you run the yo office command, you may receive prompts about the data collection policies of Yeoman and the Office Add-in CLI tools. Use the information that's provided to respond to the prompts as you see fit.

    When prompted, provide the following information to create your add-in project:

    • Choose a project type - Office Add-in Task Pane project
    • Choose a script type - JavaScript
    • What do you want to name your add-in? - Git the gist
    • Which Office client application would you like to support? - Outlook

    Screenshot of the prompts and answers for the Yeoman generator.

    After you complete the wizard, change to the project folder created by the generator (My Office Add-in) and install the npm modules by running npm install.

    Tip

    You can ignore the next steps guidance that the Yeoman generator provides after the add-in project's been created. The remainder of this unit includes all the steps you'll need to follow.

  2. Navigate to the root directory of the project.

    cd "Git the gist"

  3. This add-in will use the following libraries:

    • Showdown library to convert Markdown to HTML
    • URI.js library to build relative URLs.
    • jquery library to simplify DOM interactions.

    To install these tools for your project, run the following command in the root directory of the project.

    npm install showdown urijs jquery --SE

  4. Open your project in VS Code or your preferred code editor.

    Tip

    On Windows, you can navigate to the root directory of the project via the command line and then enter code . to open that folder in VS Code. On macOS, you'll need to add the code command to the path before you can use that command to open the project folder in VS Code.

Update the manifest

The manifest for an add-in influences how it appears in Outlook. It defines the way the add-in appears in the add-in list and the buttons that appear on the ribbon, and it sets the URLs for the HTML and JavaScript files used by the add-in.

Specify basic information

Make the following updates in the manifest.xml file to specify some basic information about the add-in:

  1. Locate the ProviderName element and replace the default value with your company name.

    <ProviderName>Contoso</ProviderName>

  2. Locate the Description element, replace the default value with a description of the add-in, and save the file.

    <Description DefaultValue="Allows users to access their GitHub gists."/>

Test the generated add-in

Before going any further, let's test the basic add-in that the generator created to confirm that the project is set up correctly.

Note

Office Add-ins should use HTTPS, not HTTP, even when you are developing. If you are prompted to install a certificate after you run the following command, accept the prompt to install the certificate that the Yeoman generator provides. You may also have to run your command prompt or terminal as an administrator for the changes to be made.

  1. Run the following command in the root directory of your project. When you run this command, the local web server starts and your add-in will be sideloaded.

    npm start

  2. In Outlook, open an existing message, and select the Show Taskpane button.

  3. When prompted with the WebView Stop On Load dialog box, select OK.

    Note

    If you select Cancel, the dialog won't be shown again while this instance of the add-in is running. However, if you restart your add-in, you'll see the dialog again.

If set up correctly, the task pane will open and render the add-in's welcome page.

Screenshot of button and task pane added by the sample.

Summary

In this exercise, you learned how to create your first Outlook add-in project and load it in the Outlook client.

Test your knowledge

1.

What are the following types of mail add-ins supported in Outlook?

2.

The two primary options for creating new add-in projects are which of the following?