Skip to content

Commit 0f70353

Browse files
Rick-KirkhamAlexJerabek
Rick-Kirkham
and
AlexJerabek
authored
[All Hosts] (devx) new article guidance for uninstalling add-ins (#4970)
* [All Hosts] (devx) new article guidance for uninstalling add-ins * format fixes * remove blank lines from end * fix ms.topic * various fixes * build errors * add warnings about Exchange propagation * remove view suggestions from links * link fix * Apply suggestions from code review Co-authored-by: Alex Jerabek <[email protected]> * review changes * small fix * format fix * format fix * format fix --------- Co-authored-by: Alex Jerabek <[email protected]>
1 parent c9102b1 commit 0f70353

File tree

5 files changed

+148
-0
lines changed

5 files changed

+148
-0
lines changed

‎docs/images/addinRegistrationWindows.png

58.9 KB
Loading

‎docs/images/addinRegistrationWindowsDeveloperSubkeys.png

9.47 KB
Loading

‎docs/images/addinRegistrationWindowsManifestPath.png

47.3 KB
Loading

‎docs/testing/uninstall-add-in.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: Uninstall add-ins under development
3+
description: Learn how to prevent incomplete uninstallation of add-ins you are developing and how to remove incompletely uninstalled add-ins under development.
4+
ms.topic: troubleshooting-problem-resolution
5+
ms.date: 12/28/2024
6+
ms.localizationpriority: medium
7+
---
8+
9+
# Uninstall add-ins under development
10+
11+
Incompletely removed add-ins can leave artifacts on your computer, such as custom ribbon buttons or registry entries, during development. In this article, we call these "ghost add-ins".
12+
13+
Outlook add-ins also might add these artifacts to other computers when you sign into Outlook on them with the same ID as you used to develop the add-in.
14+
15+
> [!IMPORTANT]
16+
> When you sign into Outlook, it downloads from Exchange, and sideloads, all the Outlook add-in manifests that are associated with your ID, *including add-ins that you are developing on a different computer using the same ID*. For example, any custom ribbon buttons defined in the manifest will appear for the add-in.
17+
>
18+
> If the URLs in the manifest point to a non-localhost server and that server is running and accessible to the non-development computer, then Outlook caches the add-in's files in the local file system and the add-in usually runs normally on the computer. Otherwise, the add-in doesn't function, but visible parts of it, such as custom ribbon buttons appear. They have the labels defined in the manifest. The add-in's button icons also appear if they were ever cached locally on the non-development computer and the cache was never cleared. Icon files aren't stored with Exchange, so if they were never cached on the non-development computer (or the cache has been cleared), then the buttons have default icons.
19+
>
20+
> Until the add-in's registration is removed from Exchange, the add-in will continue to appear. See [Remove a ghost add-in](#remove-a-ghost-add-in) for information about removing the registration in Exchange.
21+
22+
This article provides some guidance to minimize the chance of these problems and to resolve them if they occur.
23+
24+
## Prevent the problems
25+
26+
When an add-in is sideloaded, several things happen:
27+
28+
- A web server, usually on localhost, is started to serve the add-in's files (such as the HTML, CSS, and JavaScript files).
29+
- These same files are cached on your development computer.
30+
- The add-in is registered with the development computer. The registration is done with Registry entries on a Windows computer or with certain files saved to the file system on a Mac.
31+
- Most tools for sideloading add-ins automatically open the Office application that the add-in targets. The tools also populate the application with any custom ribbon buttons or context menu items that are defined in the add-in's manifest.
32+
- For an Outlook add-in, the add-in's manifest is registered with the Exchange service.
33+
34+
### Use your tool's uninstall facility
35+
36+
To prevent ghost add-ins, end every testing, debugging, and sideloading session by using the uninstall (also called unacquire) option that is provided by the tool that you used to start the session. Doing this reverses the effects of sideloading, as stated earlier in this article.
37+
38+
The following list identifies, for each tool, how to uninstall but doesn't describe the procedures or syntax in detail. *Be sure to use the links to get complete instructions.*
39+
40+
> [!NOTE]
41+
> Some of these tools don't close the Office application that opened automatically. In that case, close the application manually immediately after ending the session.
42+
43+
- **Yeoman generator for Office Add-ins (Yo Office)**: Use the `npm stop` script at the same command line where you started the session with `npm start`. For more information, see the various articles in the **Get started** and **Quick starts** sections and [Remove a sideloaded add-in](sideload-office-add-ins-for-testing.md).
44+
- **Teams Toolkit for Visual Studio Code**: Select **Run** | **Stop Debugging** in Visual Studio Code. For more information, see the last step of [Create an Outlook Add-in project](../develop/teams-toolkit-overview.md#create-an-outlook-add-in-project) which also applies to non-Outlook add-ins.
45+
- **Office Add-in Development Kit for Visual Studio Code**: With the Office Add-in Development Kit extension open, select **Stop Previewing Your Office Add-in**. For more information, see [Stop testing your add-in](../develop/development-kit-overview.md?tabs=vscode#stop-testing-your-office-add-in).
46+
- **office-addin-debugging tool**: Use the `office-addin-debugging stop` command at the same command line where you started the session with `office-addin-debugging start`. For more information, see [Sideload with the Office-Addin-Debugging tool](../develop/convert-xml-to-json-manifest.md#sideload-with-the-office-addin-debugging-tool).
47+
- **Teams Toolkit CLI**: Use the `teamsapp uninstall` command at the same command line where you started the session with `teamsapp install`. For more information, see [Sideload with the Teams Toolkit CLI](../develop/convert-xml-to-json-manifest.md#sideload-with-the-teams-toolkit-cli-command-line-interface).
48+
- **Visual Studio**: Select **DEBUG** | **Stop debugging** in the menu, or press SHIFT-F5, or click the square red "stop" button on the debugging bar. Alternatively, closing the Office application also stops the session and uninstalls the add-in. For more information, see [First look at the Visual Studio debugger](/visualstudio/debugger/debugger-feature-tour).
49+
50+
## Remove a ghost add-in
51+
52+
To remove a ghost add-in, you need to remove the artifacts that were created when it was last sideloaded, remove it's local registration, and for Outlook add-ins remove it's registration in Exchange.
53+
54+
The process for removing the add-in varies depending on whether the add-in is for Outlook or some other Office application.
55+
56+
> [!NOTE]
57+
> In the [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md), an add-in can be configured to support Outlook and one or more other Office applications; that is, there is more than one member of the "extensions.requirements.scopes" array in the manifest and one of the members is "mail" (or the "extensions.requirements.scopes" property isn't present). Treat an add-in that is configured in this way as an Outlook add-in.
58+
59+
If the ghost add-in is not an Outlook add-in, skip to the section [Remove the add-in artifacts](#remove-the-add-in-artifacts).
60+
61+
### Remove the Exchange registration of a ghost Outlook add-in
62+
63+
1. Log into Outlook with the same ID you used when you sideloaded the add-in.
64+
1. Open PowerShell as an Administrator.
65+
1. Run the following commands. Answer "Yes" to all confirmation prompts.
66+
67+
```powershell
68+
Install-Module -Name ExchangeOnlineManagement -RequiredVersion 3.4.0
69+
Set-ExecutionPolicy RemoteSigned
70+
Connect-ExchangeOnline
71+
```
72+
73+
> [!NOTE]
74+
> If the `Connect-ExchangeOnline` command returns the error "ActiveX control '8856f961-340a-11d0-a96b-00c04fd705a2' cannot be instantiated because the current thread is not in a single-threaded apartment", just run the command a second time. This is a well-known bug.
75+
76+
1. Run the following command. Answer "Yes" to all confirmation prompts.
77+
78+
```powershell
79+
Get-App | Format-Table -Auto DisplayName,AppId
80+
```
81+
82+
A list of the add-ins installed on Outlook displays. These will include built-in Microsoft add-ins and add-ins you have installed. Any ghost Outlook add-ins will also be listed.
83+
84+
1. Find the ghost add-in in the list. If it was created with Yo Office or another Microsoft tool, it probably has the name "Contoso Task Pane Add-in".
85+
1. Copy the App ID (a GUID) of the add-in. You need it for later steps.
86+
1. Run the command `Remove-App -Identity {{The GUID OF YOUR ADD-IN HERE}}` (e.g., `Remove-App -Identity 26ead0cb-10dd-4ba2-86c6-4db111876652`). This command removes the add-in from Exchange.
87+
88+
> [!WARNING]
89+
> The removal of the registration needs to propagate to all Exchange servers. Wait at least three hours before continuing with the next step.
90+
91+
1. Continue with the section [Remove the add-in artifacts](#remove-the-add-in-artifacts).
92+
93+
### Remove the add-in artifacts
94+
95+
> [!IMPORTANT]
96+
> Carry out this procedure on all devices on which you have had the add-in sideloaded.
97+
98+
1. Log out from all Office applications and then close them all, including Outlook.
99+
1. [Clear the Office cache](clear-cache.md). If the ghost add-in supports Outlook, use [Clear the cache in Outlook manually](clear-cache.md#manually-clear-the-cache-in-outlook).
100+
1. Continue with the section [Remove the local registration](#remove-the-local-registration).
101+
102+
### Remove the local registration
103+
104+
> [!IMPORTANT]
105+
> Carry out this procedure on all computers on which you have had the add-in sideloaded.
106+
107+
1. Delete the local registration of the ghost add-in. The process varies depending on the operating system.
108+
109+
#### [Windows](#tab/windows)
110+
111+
1. Open the **Registry Editor**.
112+
1. Navigate to **Computer\HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\WEF\Developer**. This key lists the add-ins that are currently sideloaded, or were sideloaded in the past and weren't fully uninstalled. The **Data** value for each entry is the path to the add-in's manifest. The **Name** value varies depending on which version of which tool was used to create and sideload the add-in. If Visual Studio was used, the name is typically is also the path to the manifest. For other tools, the name is typically the add-in's ID. When an Office application launches, it reloads all add-ins listed in this key (that support the Office application). Reloading may have no practical or discernable effect if the add-in's artifacts have been deleted from the cache, or the manifest no longer exists at the path, or the add-in's files aren't being served by a server.
113+
114+
Find the entry for the ghost add-in and delete it. If it is an Outlook add-in, then you have the ID from [removing the Exchange registration](#remove-the-exchange-registration-of-a-ghost-outlook-add-in). You can also use the path in the **Data** column to find the manifest to help identify the add-in the entry refers to and read the ID from the manifest. If any manifests listed in the **Data** column no longer exist at the specified path, then delete the entries for those manifests.
115+
116+
:::image type="content" source="../images/addinRegistrationWindowsManifestPath.png" alt-text="The Windows registry for the key named Computer\HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\WEF\Developer." border="false":::
117+
118+
1. Expand the **... Developer** node in the registry tree. Look for a subkey whose name is the same ghost add-in's ID. If it is there, delete it.
119+
120+
:::image type="content" source="../images/addinRegistrationWindowsDeveloperSubkeys.png" alt-text="The Windows registry for the key named Computer\HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\WEF\Developer expanded to show subkeys." border="false":::
121+
122+
1. Navigate to **Computer\HKEY_USERS\\{SID}\Software\Microsoft\Office\16.0\WEF\Developer**, where **{SID}** is the [SID](/windows-server/identity/ad-ds/manage/understand-security-identifiers) of the user you were signed in with when you sideloaded the add-in, and repeat the preceding two steps.
123+
1. Navigate to **Computer\HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Common\CustomUIValidationCache**. In the **Name** column, find all the entries that begin with the add-in's ID (a GUID) and delete them. Then navigate to **Computer\HKEY_USERS\\{SID}\Software\Microsoft\Office\16.0\Common\CustomUIValidationCache**, where **{SID}** is the SID of the user you were signed in with when you sideloaded the add-in, and repeat the process.
124+
125+
:::image type="content" source="../images/addinRegistrationWindows.png" alt-text="The Windows registry for the key named Computer\HKEY_USERS\SID\Software\Microsoft\Office\16.0\Common\CustomUIValidationCache**, where SID is the SID of a user." border="false":::
126+
127+
#### [Mac](#tab/mac)
128+
129+
For non-Outlook add-ins, the local registration on a Mac is removed when you clear the cache. See [Remove the add-in artifacts](#remove-the-add-in-artifacts).
130+
131+
For ghost Outlook add-ins, remove the local registration on a Mac by using the **Add-Ins for Outlook** dialog in Outlook. Follow the guidance at [Remove a sideloaded Outlook add-in](../outlook/sideload-outlook-add-ins-for-testing.md#remove-a-sideloaded-add-in).
132+
133+
---
134+
135+
2. If you are removing an Outlook add-in, continue with the section [Test for removal of Outlook add-ins](#test-for-removal-of-outlook-add-ins).
136+
137+
### Test for removal of Outlook add-ins
138+
139+
Open Outlook with the same identity you used when you created the add-in. If artifacts from the add-in (such as custom ribbon buttons) reappear after a few minutes or if event handlers from the add-in seem to be active, then the removal of the add-in's registration from Exchange hasn't propagated to all Exchange servers. Wait at least three hours and then repeat the procedures in the sections [Remove the add-in artifacts](#remove-the-add-in-artifacts) and [Remove the local registration](#remove-the-local-registration) on the computer where you observed the artifacts.
140+
141+
## See also
142+
143+
- [Troubleshoot development errors with Office Add-ins](troubleshoot-development-errors.md)
144+
- [Clear the Office cache](clear-cache.md)
145+
- The PowerShell reference for [Install-Module](/powershell/module/powershellget/install-module), [Set-ExecutionPolicy](/powershell/module/microsoft.powershell.security/set-executionpolicy), [Connect-ExchangeOnline](/powershell/exchange/connect-to-exchange-online-powershell), and [Get-App](/powershell/module/exchange/get-app).

‎docs/toc.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,9 @@ items:
350350
- name: Clear the Office cache
351351
href: testing/clear-cache.md
352352
displayName: uninstall, sideload
353+
- name: Uninstall add-in under development
354+
href: testing/uninstall-add-in.md
355+
displayName: uninstall
353356
- name: Debug with runtime logging
354357
href: testing/runtime-logging.md
355358
- name: Debug a function command with a non-shared runtime

0 commit comments

Comments
 (0)