Proposal

Interfaces

/**
 * Extensions that want to contribute their own environment creation can do that by registering an object
 * that implements this interface.
 */
export interface CreateEnvironmentProvider {
    /**
     * This API is called when user selects this provider from a QuickPick to select the type of environment 
     * user wants.
     * Returns: {@link Environment}
     * Exceptions:
     *     CancellationError: Is the user exits creation at any point or cancels creation this should be thrown
     *     Back <TBD>: User clicked on the back button.
     *     CreateEnvironmentError <TBD>:
     */
    createEnvironment(options?: CreateEnvironmentOptions): Promise<Environment | undefined>;

    /**
     * Display name for the creation provider
     */
    name: string;

    /**
     * Description displayed to the user in the QuickPick.
     */
    description: string;
}

/**
 * Options to be used when creating an environment.
 */
export interface CreateEnvironmentOptions {
    /**
     * Default `true`. If `true`, the environment creation handler is expected to install packages.
     */
    installPackages?: boolean;

    /**
     * Default `true`. If `true`, the environment creation provider is expected to add the environment to ignore list
     * for the source control.
     */
    ignoreSourceControl?: boolean;

    /**
     * Default `false`. If `true` the creation provider should show back button when showing QuickPick or QuickInput.
     */
    showBackButton?: boolean;

    /**
     * Default `true`. If `true`, the environment will be selected as the environment to be used for the workspace.
     */
    selectEnvironment?: boolean;
}

/**
 * Params passed on `onWillCreateEnvironment` event handler.
 */
export interface WillCreateEnvironmentParams {
    /**
     * Options used to create environment.
     */
    options: CreateEnvironmentOptions | undefined;
}

/**
 * Params passed on `onWillCreateEnvironment` event handler.
 */
export interface WillCreateEnvironmentParams {
    /**
     * Options used to create environment.
     */
    options: CreateEnvironmentOptions | undefined;
}

/**
 * Params passed on `onDidCreateEnvironment` event handler.
 */
export interface DidCreateEnvironmentParams {
    /**
     * Options used to create environment.
     */
    options: CreateEnvironmentOptions | undefined;

    /**
     * Reason for event trigger
     */
    reason: 'cancel' | 'back' | 'completed' | 'error';

    /**
     * Created environment
     */
    environment: Environment | undefined;

    /**
     * Error if any occurred during environment creation
     */
    error?: Error;
}

Functions

/**
 * This API should be called to register an environment creation provider. It returns a (@link Disposable} which
 * can be used to remove the registration.
 */
export function registerCreateEnvironmentProvider(provider: CreateEnvironmentProvider): Disposable;

/**
 * This API can be used to detect when environment create starts for any provider.
 */
export onWillCreateEnvironment: Event<WillCreateEnvironmentParams>;

/**
 * This API can be used to detect when environment create completed for any provider.
 */
export onDidCreateEnvironment: Event<DidCreateEnvironmentParams>;

/**
 * This API will show a QuickPick to select an environment provider from available list of providers. Based on the selection
 * the `createEnvironment` will be called on the provider.
 */
export createEnvironment(options: CreateEnvironmentOptions) : Promise<Environment | undefined>

Alternatives

`createEnvironment`

/**
 * Extensions that want to contribute their own environment creation can do that by registering an object
 * that implements this interface.
 */
export interface CreateEnvironmentProvider {
    /**
     * This API is called when user selects this provider from a QuickPick to select the type of environment 
     * user wants.
     * Returns: {@link Environment}
     */
    createEnvironment(options?: CreateEnvironmentOptions): Promise<Environment | CreateEnvironmentActionOrError>;

    /**
     * Display name for the creation provider
     */
    name: string;

    /**
     * Description displayed to the user in the QuickPick.
     */
    description: string;
}

export interface CreateEnvironmentActionOrError {
    /**
     * User action that resulted in exit from the create environment flow.
     */
    action?: 'cancel' | 'back';

    /**
     * Error if any occurred during environment creation.
     */
    error?: Error;

}

API for create environment #20697

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions