Dev notes on using extension services

[roblourens]

Inspired by #236537

I've found it a little confusing to find the right extension service to work with so here are some random notes on things that have tripped me up.

• There are many different services with "extension" in the name, and when I need to do something, it's hard to know where to start.
  • Probably the most common ones are IExtensionService, IExtensionsWorkbenchService, IExtensionManagementService, and I don't fully understand the distinction
• In the above issue, we used IExtensionManagementService#getInstalled

  vscode/src/vs/platform/extensionManagement/common/extensionManagement.ts

  Line 576 in 820447a

  getInstalled(type?: ExtensionType, profileLocation?: URI, productVersion?: IProductVersion): Promise<ILocalExtension[]>;

  to check whether the Copilot extension was installed. This seemed reasonable but it actually returns all local and remote extensions, whether enabled or disabled due to being in the wrong EH. And, it returns them the two sets in random order based on a race. I think this is a serious footgun.
  • And I think we've made the same mistake in other places. If I look at references to getInstalled I see a lot of usages. eg I get @ext: completions in the settings editor for workspace extensions in a remote window that are only installed locally and not on the remote
  • I think IExtensionsWorkbenchService#queryLocal was the right thing to use but there's also IExtensionService#extensions and I'm not sure what the difference is
• There are two different types called IExtension at

  vscode/src/vs/workbench/contrib/extensions/common/extensions.ts

  Line 56 in 820447a

  export interface IExtension {

  and

  vscode/src/vs/platform/extensions/common/extensions.ts

  Line 309 in 820447a

  export interface IExtension {

• The name queryLocal and ILocalExtension were a little confusing now that "remote extensions" exist

Some things that might help could be some tsdoc on the services and methods that explain when to use them or what exactly they return. Or a .md doc file with a "guide to extensions services" that lays this stuff out.