Tried to follow "Build your first Outlook add-in" - Sideloading not happening

[jorgk3]

I've tried to follow Build your first Outlook add-in and got to the point where the add-in is (supposedly) sideloaded:

P:\testaddon>npm start

> office-addin-taskpane-js@0.0.1 start
> office-addin-debugging start manifest.xml

Debugging is being started...
App type: desktop
Enabled debugging for add-in 4e826288-5cf3-43a1-b464-bda2bd2d1818.
Starting the dev server... (webpack serve --mode development)
The dev server is running on port 3000. Process id: 10020
Sideloading the Office Add-in...
Launching outlook via C:\Program Files\Microsoft Office\Root\Office16\OUTLOOK.EXE
Debugging started.

Outlook desktop is started and this panel appears:

My OL version:

The description says that when viewing opening a message, a new button "Show Taskpane" should appear. This is not the case. I've also set up this more sophisticated example. That also builds and loads, albeit with these errors when converting the JSON manifest to XML:

Successfully converted manifest to xml:
 13 Feb 2023 21:38:29 [Error] DeserializeJson : Cannot unmarshal type CapabilityType Path 'extensions[0].autoRunEvents[0].requirements.capabilities[0].name', line 48, position 49.
13 Feb 2023 21:38:29 [Error] DeserializeJson : Cannot unmarshal type CapabilityType Path 'extensions[0].runtimes[1].requirements.capabilities[0].name', line 107, position 49.

However, no add-in action is detected. Apparently a warning should be shown for messages sent with certain keywords (picture, document) but without attachment.

Manually sideloading the add-in into Outlook doesn't work since this page https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/sideload-outlook-add-ins-for-testing?tabs=windows doesn't reflect what happens in my Outlook. I have to UI to add add-ins manually, clicking "Get Add-ins" takes me right to the OWA page. BTW, I successfully installed an add-in, Emoji, which works in Outlook desktop and OWA.

Most likely I'm doing something wrong, but the documentation doesn't actually allow for the troubleshooting of the problem.

Two more questions:

1. In the tutorial mentioned in the first paragraph, there is a taskpane.html and a taskpane.js. The JS file isn't referenced anywhere, so how is that loaded.
2. How can one debug this stuff in general. Browsers usually have developer tools for browser add-on development, also one can write stuff to the error console using console.log() etc. How is this done with this type of add-in? Maybe a link to the respective documentation wouldn't go astray.
3. How do you list sideloaded add-ins in Outlook? I only found UI for COM/VSTO add-ins.

[jorgk3]

Additional information: I'm using an company (on-promise) Exchange server. After installing the add-in with OWA, it started working in the Outlook desktop. That's not expected behaviour, is it? It still doesn't show up in the OWA UI though. Disabling it via OWA makes it disappear from OL desktop. Is that what sideloading is meant to mean? You need need to install in OWA for the add-in to work locally?

[AlexJerabek]

Thanks for creating this issue @jorgk3. I'm sorry to hear you're having difficulties getting your add-in to sideload.

@samantharamon, could you please investigate?

[samantharamon]

Thanks for reaching out and providing information on your experience, @jorgk3.

The Outlook quick start should work in a supported Outlook client version in an on-premises Exchange environment, provided that your organization allows add-in installation and sideloading (see Add-ins for Outlook in Exchange Server). From your last comment, it's also possible that optional connected experiences may have been turned off by your admin.

When you get a chance, could you provide additional details about the Outlook client you're using? To do this, in Outlook, select File > Office Account > About Outlook.

If you don't have a requirement to develop Office Add-ins in your company's environment, we invite you to join the Microsoft 365 Developer Program. This program gives you access to a free Microsoft 365 E5 sandbox, which would aid your development journey.

Regarding your other questions:

1. The Yeoman generator you used to create the Outlook quick start does most of the heavy lifting to build your project, sideload the add-in, and create the necessary dependencies. To learn more, see Create Office Add-in projects using the Yeoman Generator.
2. Overview of debugging Office Add-ins is a great place to start learning about debugging add-ins.
3. The article you linked to (Sideload Outlook add-ins for testing) contains guidance on viewing and managing sideloaded add-ins for supported clients, although it may not be working quite as expected on your end due to possible constraints in your workplace system.

[jorgk3]

Thank you for the answer. The OL version is stated in the original comment. I've also checked the version of the installed on-premise Exchange: 2019 CU 12 Build: 15.02.1118.021. Latest Version. "optional connected experiences" is turned on in the OL client, I don't know about the server setting.

In the meantime we've noticed this (strange) behaviour: If the add-on is also added in the Outlook Web Access (see testaddon)

it works in the local OL client. As soon as its turned off in OWA, it stops working in the OL client. I don't think this is right since sideloading should be purely local, but this is how it behaves.

Colleagues have also experimented, and they found that working with VS instead of Yeoman gave immediate results: https://learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/outlook-quickstart?tabs=visualstudio

[samantharamon]

Thanks, @jorgk3. To help us investigate this further, would you be able to run a Fiddler trace and privately share it with us? For assistance with Fiddler, please refer to the documentation in https://www.telerik.com/fiddler. The trace should start from when your Outlook client is started to about a minute after clicking OK from the Register Outlook Developer Add-in Manifest dialog.

To share the trace, please create a private GitHub repository, add the trace to it, then @mention me in the repo for access.

[jorgk3]

Thanks for the reply. Will do in the next few days. For Fiddler, I'm planning to use the "Fiddler Classic" for Windows. If that's not the right choice, please let me know.

[samantharamon]

Thanks, @jorgk3. Fiddler Classic should work for your development environment.

[ghost]

This issue has been automatically marked as stale because it is marked as needing author feedback but has not had any activity for 4 days. It will be closed if no further activity occurs within 3 days of this comment. Thank you for your interest in Office Add-ins!

[jorgk3]

Hey, @msftbot, you don't allow people to work on other projects or take a vacation 😞?

[samantharamon]

Apologies, @jorgk3. Rest assured that I'm keeping an eye out on this issue, so that it doesn't get closed.

[jorgk3]

I've installed Fiddler and started the add-in via npm start which Fiddler was running. It basically logs all the network traffic to the company's mail server. In the log, I don't see any useful information. For example there are many log files containing:

This is a CONNECT tunnel, through which encrypted HTTPS traffic flows.
To view the encrypted sessions inside this tunnel, enable the Tools > Options > HTTPS > Decrypt HTTPS traffic option.

There are a few connections from OL to mail.. which is the company's mail server and a lot of unsuccessful connections, like so: [Fiddler] DNS Lookup for "exchange.intranet.<domain>.<tld>" failed. System.Net.Sockets.SocketException No such host is known.

So what exactly are you after? As we stated, the addin is loaded via npm start if it's also uploaded to OWA and enabled there. It's not side-loaded into OL locally if disabled in OWA.

So please let me know which network traffic to look out for.

[samantharamon]

Regarding the message about encrypted traffic, please see Enable HTTPS traffic decryption for instructions on how to view these sessions.

We're looking for the GetAppManifests EWS call made to the Exchange server, which is responsible for fetching add-ins. There could be multiple GetAppManifests requests, so it will be great to keep Fiddler running from when Outlook boots till about 30 seconds after the add-in registration dialog is closed.

[jorgk3]

Here's what I've done. With the test add-in loaded into the company's OWA, I've run npm start to launch Outlook and sideload the add-in.

While this was happening, I ran Fiddle (with HTTPS decryption) and then saved the trace and unpacked it, then looked for raw files containing GetAppManifests and looked at the responses.

In the case where the test add-in is enabled at the server, the add-in is reported with <t:EnabledStatus>True</t:EnabledStatus>. It also loads and works in local OL.

In the case where the test add-in is disabled at the server, thethe "enabled status" is reported as False. In this case it's not working in local OL.

I checked that the XML really relates to the test add-in by inspecting the <t:Manifest>, that is base64-decoding it. In the decoded manifest I see:

  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="testaddon" />
  <Description DefaultValue="A template to get started." />

It looks like there is a general misunderstanding here. Unless I read it incorrectly, the documentation seems to suggest that you can develop OL add-ins locally and "sideload" them into a local OL app. When you do that, the prompt (shown in the very first comment here) "There is an attempt to register an Outlook Developer Add-in ..." asks for permission to execute.

The observed behaviour is that this doesn't work, unless the add-in is also installed into OWA on the server and enabled there. If it's a local sideload, the add-in should always load, and not just when it's also installed into OWA and enabled there. Which part of the concept have I misunderstood?

Or maybe the process behind npm start should also upload the add-in to the server and enable it? Colleagues are using the "Visual Studio method" without problem. Does this upload the add-in to the server?

EDIT: I've tried the "MS VS way", the add-in is also uploaded to the server. So I'm still wondering how this is meant to work for "local" development for Outlook and not OWA.

[samantharamon]

Thanks for the update, @jorgk3. Would it be possible to share your trace with us via a private repository on GitHub, so that we can investigate it further? You should be able to sideload the add-in in the desktop app without having to go through OWA, so we're hoping something in the trace will indicate why you're not seeing this behavior on your end.

Visual Studio hosts your add-in on your local IIS server. Add-ins sideloaded using npm start are hosted on the localhost server by webpack-dev-server (see Create Office Add-in projects using the Yeoman Generator for more details).

[jorgk3]

Done. You should have received an invite.

I have some more comments/problems: Following https://learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/outlook-quickstart?tabs=visualstudio I created an Outlook Web Add-in. MS VS eventually prompts for credentials:

This then connects to the company's on-premise Exchange server, opens OWA and installs the add-in there. However, the add-in doesn't show up in the OWA UI like it does show up in the local Outlook UI when doing it the Yeoman way (with add-in also installed in OWA). So in conclusion, maybe something wrong with the company's Exchange server which is still at version 2019 (Build: 15.02.1118.021).

[samantharamon]

Interesting. Thanks for sharing the traces and providing additional information on what you're seeing. I'll take this back to the team for further investigation.

[jorgk3]

Visual Studio hosts your add-in on your local IIS server. Add-ins sideloaded using npm start are hosted on the localhost server by webpack-dev-server

Can you please explain the connection between local add-on hosting via IIS server or webpack-dev-server server. Why does following https://learn.microsoft.com/en-us/office/dev/add-ins/quickstarts/outlook-quickstart?tabs=visualstudio prompt credentials to subsequently open this OWA UI of the respective account and install the add-in there, too. That is the observerd behaviour for the company's on-premises server. I tried using outlook,com (outlook.live.com) but couldn't find any UI to manage add-ins (very strange), hence I couldn't check whether it was installed there, too.

Coincidentally I came across https://github.com/OfficeDev/generator-office/issues/767. There the reporter states: "When I try the same add-in in the desktop app on macOS or Windows, it looks as though the add-in was properly added and it shows up under "Custom Addins". In my local Outlook client, I can't see such functionality, I can only list the COM/VSTO add-ins.

[samantharamon]

Sideloading through the Visual Studio toolset was first implemented before the yo office option was available. At that time, installing the add-in to OWA was the only option available. When the capability to have the Outlook client install a manifest from a specified directory was then made available, it was implemented in the yo office toolset. To clarify, however, your sideloaded add-in, no matter which option you use to sideload, should appear in all the supported platforms you use. Sideloading installs the add-in to the user's mailbox on Exchange; not just to the client. For example, if you sideload using npm start, the add-in will load Outlook on Windows, but will also appear in Outlook on the web when you load the client. If you sideload through Visual Studio, your add-in will load Outlook on the web, but the add-in will also appear in Outlook on Windows when you open the client.

We're still investigating the cause of the issue you're experiencing. The other EWS call we're trying to locate in the traces you provided, but couldn't find, is GetAppMarketplaceUrl. When you get a chance, could you run through the same process you did before, that is, start the trace from when your Outlook client is started after sideloading, but this time, please leave it running for about five minutes? We're hoping this will capture more information to help us understand this issue better. Thank you.

[ghost]

This issue has been automatically marked as stale because it is marked as needing author feedback but has not had any activity for 4 days. It will be closed if no further activity occurs within 3 days of this comment. Thank you for your interest in Office Add-ins!

[jorgk3]

Thanks for the detailed explanation. So the add-on is always installed on the Exchange server and "deployment" is controlled from there, also via the GetAppManifests call. Looks like in my case, the add-in isn't installed on the Exchange server. That's why things only start working when you install it there manually. I've added another file to the private repo bad-again.saz. This time the GetAppMarketplaceUrl calls are captured in files 108 and 358. I'll try the same via an account at O365 later.

[jorgk3]

OK, I tried the same with an address @outlook,com. Everything worked fine. npm start starts the local OL client, the add-in is functional. Visiting the web interface at outlook.live.com, the add-in is equally present and functional.

Let's blame the non-functional side-loading on the company's on-premises server which is probably not configured correctly. Ironically, the company has decommissioned that server and moved to an O365 subscription.

Feel free to close the ticket.

---

Unrelated: One day I'll work out how find the UI to manage add-in in the web UI. It looks like this on the on-premises OWA:

but on outlook.live.com I can't find the equivalent UI (which is frustrating to someone whose been using computers for decades). One should think that searching for "add-in" in the Settings search box should find something, but it doesn't.

UPDATE: Oh boy, you need to click the three-dots menu on a message header (left of forward). Then Get Add-ins/My add-ins. That's really very well hidden.

[jorgk3]

There is another thing that I'd appreciate if you could clarify: You said:

Sideloading installs the add-in to the user's mailbox on Exchange; not just to the client.

But also:

Visual Studio hosts your add-in on your local IIS server. Add-ins sideloaded using npm start are hosted on the localhost server by webpack-dev-server ...

So that's the confusion. It looks like the manifest is hosted on the Exchange server, however, the actual code is served from a local server, like https://localhost:44384 in the MS VS case. Observed behaviour is also that local code changes, even not using the MS VS editor (but some external one), take immediate effect since the add-on code is served from the local directory via the local server.

So how does hosting the add-in both on the Exchange server and locally hang together?

[samantharamon]

Thanks for the update, @jorgk3. I'm glad to hear things are now working as expected, at least in your outlook.com account. If you find yourself in need of a separate development sandbox with a free Microsoft 365 E5 license, we invite you to check out the Microsoft 365 Developer Program.

UPDATE: Oh boy, you need to click the three-dots menu on a message header (left of forward). Then Get Add-ins/My add-ins. That's really very well hidden.

I'm sorry to hear about the extra trouble you experienced trying to locate the Get Add-ins option in outlook.live.com. For what it's worth, some guidance is provided in Using add-ins in Outlook.com, but it requires some updates. I'll create an internal work item to get this updated.

So how does hosting the add-in both on the Exchange server and locally hang together?

The XML manifest that you sideload (or that npm sideloads on your behalf) contains your add-in project's source location files, specifically, using the SourceLocation element. These source files, i.e., HTML, JavaScript, and CSS files, can be hosted locally or on a web server. When the manifest is communicated to Exchange, Exchange then uses the referenced location in the manifest to run the add-in on your Outlook client. To learn more about this process, see (Office Add-ins XML manifest)[https://learn.microsoft.com/office/dev/add-ins/develop/add-in-manifests] and Outlook add-in manifests.

Thank you again for your patience as we worked on your issue. Please don't hesitate to respond to this issue or create a new one if you need additional assistance. I'll let the bot close this out in three days if we don't hear back.

[jorgk3]

Thanks for the additional information.

Just out of curiosity, did the content of the additional log yield any indication why it didn't work on the company's on-premises server. Or you're not looking at it any more?

Maybe the information given in this ticket could be included in in some form in https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/, maybe https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/sideload-outlook-add-ins-for-testing would be the right page. I'm sure many developers ask themselves "so how does it all hang together?"

[samantharamon]

Thanks for the great feedback, @jorgk3. I've added this as a work item on our backlog.

I shared the last trace you provided with the team to see if there was anything else that could indicate why it doesn't work on the on-premises environment. I'll keep you posted when I hear back.

[samantharamon]

Hi @jorgk3,

Based on the last trace you provided, it's likely that Outlook is unable to access the Office Config Service possibly because of its connection to the on-premises Exchange server (see line 26 in the trace that provides a 403: Access is denied error). The Config Service stores tokens that point to data needed by the Outlook client. With the in-client Store (Get Add-is button), the stored token points to the minimum version of Exchange that supports the in-client Store feature. If Outlook fails to get this stored token, by default, a browser window for the Store is opened instead (this was the behavior you were seeing).

Given this new information, as you mentioned, it's likely that the issue is with the state or configuration of the on-premises server.

[jorgk3]

Thanks for spending the time to analyse this. I'm also glad that you intend to take my suggestions onboard and improve the documentation. I think we're done here.