Performing a clean uninstall of Search extensions in Team Foundation Server

Original Post: 10/6/2018 8:38:10 AM

TFS currently supports search for Code, Work Item and WIKI. Each of these entities have their own extensions that need to be installed for the feature to be enabled for that collection. Extension install is done automatically during Search configuration (note: Work Item and WIKI search extensions are installed by default, whereas Code search is an opt-in feature). Extension can also be installed later from the Local Gallery page (http://{Server}/tfs/_gallery). Extension uninstall can be done from the “Manage extensions” page (http://{Server}/tfs/{Collection}/_admin/_extensions?tab=manage&status=active).

Extension uninstall could be required for multiple reasons –

• You might not require the feature any longer. Hence, cleaning it up would reclaim disk space taken by that entity index in the Elasticsearch machine.
• As part of troubleshooting, you might need to reset the index. Uninstalling and re-installing the extension is one of the approach (more details in the blog post here)

Extension uninstall does the following internally –

• Removes the search feature (for that entity) from the portal
• Stops all future indexing of the entity data.
• Deletes the index data for that entity in the Elasticsearch (if the ES is still accessible)
• Cleans up all tables entries associated with that entity in the Collection DB.

Getting all the above 4 (especially the last 2) is essential to ensure that future extension installation works as expected. Following are the guidance to ensure a clean uninstall –

• Disable the FaultManagement feature temporarily. That will help speed up the uninstall process (specifically in the scenario where the Elasticsearch cluster is inaccessible; such offline scenarios can potentially occur when the collection properties are pointing to some old cluster). Run the following script on Configuration DB:

declare @features dbo.typ_KeyValuePairStringTableNullable
insert into @features values('#\FeatureAvailability\Entries\Search.Server.FaultManagement\', '0')
exec prc_UpdateRegistry @partitionId=1, @identityName = '00000000-0000-0000-0000-000000000000', @registryUpdates = @features

• Go to “Manage extensions” page (http://{Server}/tfs/{Collection}/_admin/_extensions?tab=manage&status=active) and uninstall the entity extension for that collection

The extension uninstall triggers a sequence of clean up jobs per repository under that collection to delete the indices. In the [Tfs_Configuration].[dbo].[tbl_JobHistory] table, you can see delete jobs cleaning up the ES documents. There will be one job result entry for each repository in that collection.

SELECT [JobId], [StartTime], [Result], [ResultMessage]
FROM [Tfs_Configuration].[dbo].[tbl_JobHistory] as History
INNER JOIN
[Tfs_Configuration].[dbo].[tbl_ServiceHost] as ServiceHost
ON History.JobSource = ServiceHost.HostId
WHERE ResultMessage like '%Delete-SearchExtensionEventNotification%'
ORDER BY StartTime desc

• [This step applies ONLY to TFS 2017 Update 2 and earlier. The uninstall-install synchronization is built into the indexer pipeline in later releases]

Wait for 10-15 min for documents in the index to be cleaned up.

• Ensure all IndexingUnits and ChangeEvents for that entity in the Collection DB are cleaned up (run the scripts in the following sequence only)

DELETE FROM [Search].[tbl_IndexingUnitChangeEvent]
WHERE IndexingUnitId in
(
    SELECT IndexingUnitId FROM [Search].[tbl_IndexingUnit] WHERE EntityType = '%EntityType%' 
)
DELETE FROM [Search].[tbl_IndexingUnit] where EntityType = '%EntityType%'

(where, %EntityType% would be 'Code',  'WorkItem' or 'WIKI' depending on the extension being uninstalled)

• Enable back the FaultManagement feature by running the following script on Configuration DB:

declare @features dbo.typ_KeyValuePairStringTableNullable
insert into @features values('#\FeatureAvailability\Entries\Search.Server.FaultManagement\', '1')
exec prc_UpdateRegistry @partitionId=1, @identityName = '00000000-0000-0000-0000-000000000000', @registryUpdates = @features

• [This step applies ONLY to TFS 2017 Update 3 and later]

Verify that the #\Service\ALMSearch\Settings\IsExtensionOperationInProgress\%EntityType%\Uninstalled either does not exist, or is reset correctly to false.

SELECT *
FROM [<CollectionDB>].[dbo].[tbl_RegistryItems]
WHERE ParentPath = '#\Service\ALMSearch\Settings\IsExtensionOperationInProgress\%EntityType%\' and ChildItem = 'Uninstalled\'

If it is set to 'True', execute the following command to reset it:

declare @registryValue dbo.typ_KeyValuePairStringTableNullable
insert into @registryValue values('#\Service\ALMSearch\Settings\IsExtensionOperationInProgress\%EntityType%\Uninstalled\', 'False')
exec prc_UpdateRegistry @partitionId=1, @identityName = '00000000-0000-0000-0000-000000000000', @registryUpdates = @registryValue

You have now cleanly removed all footprints of the search entity extension from TFS.