|
| 1 | +/*--------------------------------------------------------- |
| 2 | + * Copyright (C) Microsoft Corporation. All rights reserved. |
| 3 | + *--------------------------------------------------------*/ |
| 4 | +import * as vscode from "vscode"; |
| 5 | +import { v4 as uuidv4 } from 'uuid'; |
| 6 | +import { LanguageClient } from "vscode-languageclient"; |
| 7 | +import { IFeature } from "../feature"; |
| 8 | +import { Logger } from "../logging"; |
| 9 | +import { SessionManager } from "../session"; |
| 10 | + |
| 11 | +export interface IExternalPowerShellDetails { |
| 12 | + exePath: string; |
| 13 | + version: string; |
| 14 | + displayName: string; |
| 15 | + architecture: string; |
| 16 | +} |
| 17 | + |
| 18 | +export class ExternalApiFeature implements IFeature { |
| 19 | + private commands: vscode.Disposable[]; |
| 20 | + private languageClient: LanguageClient; |
| 21 | + private static readonly registeredExternalExtension: Map<string, IExternalExtension> = new Map<string, IExternalExtension>(); |
| 22 | + |
| 23 | + constructor(private sessionManager: SessionManager, private log: Logger) { |
| 24 | + this.commands = [ |
| 25 | + /* |
| 26 | + DESCRIPTION: |
| 27 | + Registers your extension to allow usage of the external API. The returns |
| 28 | + a session UUID that will need to be passed in to subsequent API calls. |
| 29 | +
|
| 30 | + USAGE: |
| 31 | + vscode.commands.executeCommand( |
| 32 | + "PowerShell.RegisterExternalExtension", |
| 33 | + "ms-vscode.PesterTestExplorer" // the name of the extension using us |
| 34 | + "v1"); // API Version. |
| 35 | +
|
| 36 | + RETURNS: |
| 37 | + string session uuid |
| 38 | + */ |
| 39 | + vscode.commands.registerCommand("PowerShell.RegisterExternalExtension", (id: string, apiVersion: string = 'v1'): string => |
| 40 | + this.registerExternalExtension(id, apiVersion)), |
| 41 | + |
| 42 | + /* |
| 43 | + DESCRIPTION: |
| 44 | + Unregisters a session that an extension has. This returns |
| 45 | + true if it succeeds or throws if it fails. |
| 46 | +
|
| 47 | + USAGE: |
| 48 | + vscode.commands.executeCommand( |
| 49 | + "PowerShell.UnregisterExternalExtension", |
| 50 | + "uuid"); // the uuid from above for tracking purposes |
| 51 | +
|
| 52 | + RETURNS: |
| 53 | + true if it worked, otherwise throws an error. |
| 54 | + */ |
| 55 | + vscode.commands.registerCommand("PowerShell.UnregisterExternalExtension", (uuid: string = ""): boolean => |
| 56 | + this.unregisterExternalExtension(uuid)), |
| 57 | + |
| 58 | + /* |
| 59 | + DESCRIPTION: |
| 60 | + This will fetch the version details of the PowerShell used to start |
| 61 | + PowerShell Editor Services in the PowerShell extension. |
| 62 | +
|
| 63 | + USAGE: |
| 64 | + vscode.commands.executeCommand( |
| 65 | + "PowerShell.GetPowerShellVersionDetails", |
| 66 | + "uuid"); // the uuid from above for tracking purposes |
| 67 | +
|
| 68 | + RETURNS: |
| 69 | + An IPowerShellVersionDetails which consists of: |
| 70 | + { |
| 71 | + version: string; |
| 72 | + displayVersion: string; |
| 73 | + edition: string; |
| 74 | + architecture: string; |
| 75 | + } |
| 76 | + */ |
| 77 | + vscode.commands.registerCommand("PowerShell.GetPowerShellVersionDetails", (uuid: string = ""): Promise<IExternalPowerShellDetails> => |
| 78 | + this.getPowerShellVersionDetails(uuid)), |
| 79 | + ] |
| 80 | + } |
| 81 | + |
| 82 | + private registerExternalExtension(id: string, apiVersion: string = 'v1'): string { |
| 83 | + this.log.writeDiagnostic(`Registering extension '${id}' for use with API version '${apiVersion}'.`); |
| 84 | + |
| 85 | + for (const [_, externalExtension] of ExternalApiFeature.registeredExternalExtension) { |
| 86 | + if (externalExtension.id === id) { |
| 87 | + const message = `The extension '${id}' is already registered.`; |
| 88 | + this.log.writeWarning(message); |
| 89 | + throw new Error(message); |
| 90 | + } |
| 91 | + } |
| 92 | + |
| 93 | + if (!vscode.extensions.all.some(ext => ext.id === id)) { |
| 94 | + throw new Error(`No extension installed with id '${id}'. You must use a valid extension id.`); |
| 95 | + } |
| 96 | + |
| 97 | + // If we're in development mode, we allow these to be used for testing purposes. |
| 98 | + if (!this.sessionManager.InDevelopmentMode && (id === "ms-vscode.PowerShell" || id === "ms-vscode.PowerShell-Preview")) { |
| 99 | + throw new Error("You can't use the PowerShell extension's id in this registration."); |
| 100 | + } |
| 101 | + |
| 102 | + const uuid = uuidv4(); |
| 103 | + ExternalApiFeature.registeredExternalExtension.set(uuid, { |
| 104 | + id, |
| 105 | + apiVersion |
| 106 | + }); |
| 107 | + return uuid; |
| 108 | + } |
| 109 | + |
| 110 | + private unregisterExternalExtension(uuid: string = ""): boolean { |
| 111 | + this.log.writeDiagnostic(`Unregistering extension with session UUID: ${uuid}`); |
| 112 | + if (!ExternalApiFeature.registeredExternalExtension.delete(uuid)) { |
| 113 | + throw new Error(`No extension registered with session UUID: ${uuid}`); |
| 114 | + } |
| 115 | + return true; |
| 116 | + } |
| 117 | + |
| 118 | + private async getPowerShellVersionDetails(uuid: string = ""): Promise<IExternalPowerShellDetails> { |
| 119 | + if (!ExternalApiFeature.registeredExternalExtension.has(uuid)) { |
| 120 | + throw new Error( |
| 121 | + "UUID provided was invalid, make sure you execute the 'PowerShell.GetPowerShellVersionDetails' command and pass in the UUID that it returns to subsequent command executions."); |
| 122 | + } |
| 123 | + |
| 124 | + // TODO: When we have more than one API version, make sure to include a check here. |
| 125 | + const extension = ExternalApiFeature.registeredExternalExtension.get(uuid); |
| 126 | + this.log.writeDiagnostic(`Extension '${extension.id}' used command 'PowerShell.GetPowerShellVersionDetails'.`); |
| 127 | + |
| 128 | + await this.sessionManager.waitUntilStarted(); |
| 129 | + const versionDetails = this.sessionManager.getPowerShellVersionDetails(); |
| 130 | + |
| 131 | + return { |
| 132 | + exePath: this.sessionManager.PowerShellExeDetails.exePath, |
| 133 | + version: versionDetails.version, |
| 134 | + displayName: this.sessionManager.PowerShellExeDetails.displayName, // comes from the Session Menu |
| 135 | + architecture: versionDetails.architecture |
| 136 | + }; |
| 137 | + } |
| 138 | + |
| 139 | + public dispose() { |
| 140 | + for (const command of this.commands) { |
| 141 | + command.dispose(); |
| 142 | + } |
| 143 | + } |
| 144 | + |
| 145 | + public setLanguageClient(languageclient: LanguageClient) { |
| 146 | + this.languageClient = languageclient; |
| 147 | + } |
| 148 | +} |
| 149 | + |
| 150 | +interface IExternalExtension { |
| 151 | + readonly id: string; |
| 152 | + readonly apiVersion: string; |
| 153 | +} |
0 commit comments