Vscode: Provide API to get access to the workspace configuration file

[bpasero]

Extracted from https://github.com/Microsoft/vscode/issues/35407

[bpasero]

@alefragnani I think what I would like to avoid is that people just open that file and write into it arbitrary data. So if possible I would like to not expose the raw path. If this is only about being able to open a workspace again that was opened before we should maybe introduce some other identifier that we understand how to open.

[alefragnani]

I understand that it is _dangerous_, but people already have access to that file, because they can use Preferences: Open Workspaces Settings to add settings to it 😄 . I would like to know its path because it is how I store _favorite folders_ in my Project Manager extension. But, if you introduce another identifier that I could store, it would work just fine.

However, I would need to two new APIs, based on this identifier:

• To know the _Workspace Name_, to display it in my pick list
• Be able to Open the Workspace, just like the the vscode.commands.executeCommand("vscode.openFolder", uri, false) command does

Thanks in advance

[bpasero]

@alefragnani access via the settings API is fine imho because there we open the file for a specific purpose: adding settings. What I would want to avoid is that extensions introduce a new root-level node in that file for their own metadata (this happened in the past when extensions suddenly added files into the .vscode folder that is local to a workspace).

Your requirements make good sense to me 👍

[alefragnani]

Hi @bpasero ,

Any plans about this request? I see some improvements in Workspaces API in the latest VS Code releases and was wondering when I could see something like vscode.workspace.filename to know the workspace's path

Thanks in advance

[fabiospampinato]

I would also like an API for this, for basically the same use case as @alefragnani.

What I would want to avoid is that extensions introduce a new root-level node in that file for their own metadata

VSC could just remove extra root nodes automatically. The lack of an API for getting the path to this file doesn't really prevent people from manually adding those root nodes, for whatever reason they might want to do so.

(this happened in the past when extensions suddenly added files into the .vscode folder that is local to a workspace).

I think this is fine, I do it for some of my extensions too. It makes their configurations easier to edit (https://github.com/Microsoft/vscode/issues/41040#issuecomment-385092544) and amazingly using separate files for configuration kept them working even in multi-root workspaces (https://github.com/Microsoft/vscode/issues/47995).

[bpasero]

My current idea in https://github.com/Microsoft/vscode/commit/96a2358cc1348cd7f0f1d695544ee3d9d4a1c0fd

API:

export namespace workspace {

    /**
     * The location of the workspace. `undefined` when no folder
     * has been opened.
     */
    export const uri: Uri | undefined;
}

This will be:

• undefined if no folder or workspace is opened
• the location of the folder if a single folder is opened
• the location of the workspace file if a workspace is opened

The idea is that you can pass vscode.workspace.uri into vscode.openFolder and thus would allow to open either that folder or workspace again.

Thoughts?

[fabiospampinato]

@bpasero Shouldn't it always return the path to the relevant configuration file so that it returns /path/to/project/.vscode/settings.json if I have only one folder open and /path/to/workspace.code-workspace if I have multiple folders open? I'm not sure, for this particular issue, we'd want the path to the _folder_ instead when there's only one folder open 🤔

[alefragnani]

@bpasero just to be clear, when you say _the location of the workspace file_ it means _the location of the .code-workspace file_ right?

That sounds perfect to me 👍

[bpasero]

@fabiospampinato that is an interesting thought but would turn around this feature to something else I would argue. What is the use case for knowing the location of the settings file for the workspace given you can use the configuration APIs to add content to it?

@alefragnani here is an example depending on what is opened:

• empty window: undefined
• single folder opened: file:///Users/bpasero/Development/folder
• workspace opened: file:///Users/bpasero/Development/workspaces/myworkspace.code-workspace

[alefragnani]

@bpasero That's great!

I understand an _unsaved multi-root_ window to be undefined as well, because you actually don't have a workspace yet, right?

[fabiospampinato]

would turn around this feature to something else I would argue

@bpasero I've added my comment partially because this issue is named "Provide API to get access to the workspace _configuration file_", and I'd say the path to the settings.json file would fit more this description than the path to the folder.

What is the use case for knowing the location of the settings file for the workspace given you can use the configuration APIs to add content to it?

Those project management extensions need to know the path to the *.code-workspace file so that their users can save their workspace in the extension's projects list and re-open it from there easily. Those extensions don't actually need to modify its content at all.

I suppose the proposed workspace.uri should work fine, but it's a bit weird to me that it may point to either a json file or a folder, and it overlaps a bit with workspace.workspaceFolders since one can already retrieve the path to the actual folders from there. But on the other hand it's also nice that one can pass that value directly to vscode.openFolder. Just some feedback.

[bpasero]

@alefragnani that is a good point, I forgot to handle that case. Given that, I wonder if this new API should be strictly for workspace files only that are not untitled. Then the name should probably change too, to make that clear. I will bring this up in our API discussion call next week.

@fabiospampinato the title of this issue is misleading, I never meant to return the settings.json file from a folder workspace in case you have a single folder opened. I guess here the wording is confusing. To me, a workspace configuration file is the thing to put 1-N folders in ( = *.code-workspace). The settings.json in my mind is more like the "workspace settings file", but I see how the other description would be a fit too.

I think we should make very clear what the intent of the API is: to be able to build a list of recently opened workspaces and open them again. NOT to provide access to the underlying JSON file of workspace settings in general.

[bpasero]

Pushed an update and this is now how it behaves:

export namespace workspace {

    /**
     * The location of the workspace. Depending on the workspace that
     * is opened, the value will be:
     *  * `undefined` when no workspace or folder is opened
     *  * `undefined` when an untitled workspace is opened
     *  * the path of the folder as `Uri` if a single folder is opened
     *  * the path of the workspace file as `Uri` if a workspace is opened
     *
     * The location can e.g. be used with the `vscode.openFolder` command to
     * open the workspace again after it has been closed.
     *
     * **Example:**
     * ```typescript
     * vscode.commands.executeCommand('vscode.openFolder', uriOfWorkspace);
     * ```
     *
     * **Note:** it is not advised to use `workspace.uri` to write configuration
     * data into the file. You can use `workspace.getConfiguration().update()`
     * for that purpose which will work both when a single folder is opened as
     * well as an untitled or saved workspace.
     */
    export const uri: Uri | undefined;
}

Up for debate:

• should it still be called vscode.workspace.uri
• should it be undefined even when a single folder is opened

[jrieken]

should it still be called vscode.workspace.uri

It could be vscode.workspace.rootUri, similar to rootPath but better.

Edit: Maybe not and it might be confusing to overload this single folder cases. So, I think a better idea would be have this value defined only when opening a workspace (e.g. no folder) and to have a better name reflecting that, maybe vscode.workspace.workspaceFile

[jrieken]

Summary from the API sync:

• this should be the workspace configuration file, e.g. file://some/path/to/myWorkspace.code-workspace
• if technically possible this shold also include untitled workspaces, e.g. untitled:Hello.code-workspace (like untitled files)
• this should not be a folder and consistently be a config file only

[bpasero]

@jrieken to clarify, the suggested name is vscode.workspace.workspaceFile?

I can look into supporting untitled, though this can be weird because we always reopen untitled workspaces and they quickly get deleted when you close the window. For an extension that wants to build a list of recently opened this could be frustrating, especially since we do not really provide a method to test if the workspace is untitled or not (though you could check by the file name).

[bpasero]

PR: https://github.com/Microsoft/vscode/pull/72490

[bpasero]

Landed as proposed:

export namespace workspace {

    /**
     * The location of the workspace file, for example:
     *
     * file:///Users/name/Development/myProject.code-workspace`
     *
     * or
     *
     * `untitled:1555503116870`
     *
     * for a workspace that is untitled and not yet saved.
     *
     * Depending on the workspace that is opened, the value will be:
     *  * `undefined` when no workspace or  a single folder is opened
     *  * the path of the workspace file as `Uri` otherwise. if the workspace
     * is untitled, the returned URI will use the `untitled:` scheme
     *
     * The location can e.g. be used with the `vscode.openFolder` command to
     * open the workspace again after it has been closed.
     *
     * **Example:**
     * 
     * vscode.commands.executeCommand('vscode.openFolder', uriOfWorkspace);
     * 
     *
     * **Note:** it is not advised to use `workspace.workspaceFile` to write
     * configuration data into the file. You can use `workspace.getConfiguration().update()`
     * for that purpose which will work both when a single folder is opened as
     * well as an untitled or saved workspace.
     */
    export const workspaceFile: Uri | undefined;
}

[bpasero]

The plan is to move the API out of proposed state for this milestone. See https://github.com/microsoft/vscode/issues/76469