|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Working with Projects |
| 4 | +permalink: /projects/ |
| 5 | +nav_order: 9 |
| 6 | +--- |
| 7 | + |
| 8 | +# Working with Projects |
| 9 | + |
| 10 | +A project is a named set of class definitions, routines, include files, web application files or custom documents. All files in a project must be in the same namespace on the same InterSystems server. Each document can be associated with any number of projects. Each namespace can contain any number of projects. |
| 11 | + |
| 12 | +## Why Projects? |
| 13 | + |
| 14 | +You are not required to use projects in VS Code, but you should consider using them if: |
| 15 | + |
| 16 | +* You work [server-side](../serverside) and the `type` and `filter` [query parameters](../serverside/#filters-and-display-options) are not granular enough. |
| 17 | +* You work server-side and want to edit CSP and non-CSP files in the same workspace folder. |
| 18 | +* You work client-side and want to group together many files to export with a single click. |
| 19 | +* You are migrating from InterSystems Studio and want to keep using an existing project. |
| 20 | + |
| 21 | +{: #explorer} |
| 22 | +## Projects Explorer |
| 23 | + |
| 24 | +The easiest way to manage projects is using the Projects Explorer, which is in the [ObjectScript view](../extensionui/#objectscript-view): |
| 25 | + |
| 26 | + |
| 27 | + |
| 28 | +Initally, the Projects explorer contains a root node for each server and namespace connection that exists for the current workspace. It can be expanded to show all projects in that namespace on the server, and expanding the project node will show its contents: |
| 29 | + |
| 30 | + |
| 31 | + |
| 32 | +You can also add root nodes for namespaces on any server configured using the InterSystems Server Manager extension. To do so, click on the plus (`+`) button at the top of the view. |
| 33 | + |
| 34 | +The following sections will describe how to use the Projects Explorer and other tools to work with projects. |
| 35 | + |
| 36 | +{: #creating} |
| 37 | +## Creating Projects |
| 38 | + |
| 39 | +There are two ways to create projects in VS Code: |
| 40 | + |
| 41 | +* Right-click on a server-namespace node in the Projects Explorer and select the `Create Project` menu option. |
| 42 | +* Open the command palette and run the `ObjectScript: Create Project` command. |
| 43 | + |
| 44 | +Project names are required to be unique per server-namespace and may optionally have a description. The description is shown when hovering over the project's node in the Projects Explorer or below its name when selecting one in a dropdown menu. |
| 45 | + |
| 46 | +{: #modifying} |
| 47 | +## Modifying Projects |
| 48 | + |
| 49 | +There are three ways to add or remove items from a project: |
| 50 | + |
| 51 | +* Using the Projects Explorer: |
| 52 | + * To add items, right-click on the project node or one of the document type nodes (i.e. `Classes` or `Routines`) and select the `Add Items to Project...` menu option. If you clicked on a document type node, you will only be shown documents of that type to add. |
| 53 | + * To remove an item, right-click on its node and select the `Remove from Project` menu option. If you remove a package or directory node, all of its children will also be removed from the project. You may also right-click on the project node and select the `Remove Items from Project...` menu option to be presented with a multi-select dropdown that allows you to remove multiple items at once. |
| 54 | +* Within a workspace folder configured to view or edit documents in a project directly on the server: |
| 55 | + * To add items, right-click a root `isfs(-readonly)` folder that has the `project` query parameter in its URI and select the `Add Items to Project...` menu option. |
| 56 | + * To remove an item, right-click on its node and select the `Remove from Project` menu option. If you remove a package or directory node, all of its children will also be removed from the project. You may also right-click on a root `isfs(-readonly)` folder that has the `project` query parameter in its URI and select the `Remove Items from Project...` menu option to be presented with a multi-select dropdown that allows you to remove multiple items at once. |
| 57 | +* Using commands: |
| 58 | + |
| 59 | + Open the command palette and select the `ObjectScript: Add Items to Project...` or `ObjectScript: Remove Items from Project...` command. |
| 60 | + |
| 61 | +### Add to Project UI |
| 62 | + |
| 63 | +The `Add to Project` command implements a custom multi-select dropdown that is shown regardless of how it is invoked. Items that are in the namespace and not already in the project are shown. The elements of this UI are described in more detail below: |
| 64 | + |
| 65 | + |
| 66 | + |
| 67 | +* Title bar row: |
| 68 | + * Click the icons to show or hide system and generated items, respectively. |
| 69 | +* Input box row: |
| 70 | + * Click the check box to select all items that are currently shown. |
| 71 | + * Type in the input box to filter the items that are shown. |
| 72 | + * Click the **OK** button to add the selected items to the project. |
| 73 | +* Item rows: |
| 74 | + * Click the check box to select the item. If the item is a package or CSP directory, all of its contents will be selected as well, even though the check boxes for those items don't appear selected. |
| 75 | + * The icon preceding the name represents its type. It corresponds to the icons in the Projects Explorer and [ObjectScript Explorer](../extensionui/#objectscript-view). |
| 76 | + * The more prominent text is the short name of the item, as it would appear in a file system. |
| 77 | + * The less prominent text is the full name of the item, including its package or CSP directory. |
| 78 | + * Click the arrow icon at the far right of the row to show or hide its contents. |
| 79 | + |
| 80 | +{: #deleting} |
| 81 | +## Deleting Projects |
| 82 | + |
| 83 | +There are two ways to delete projects in VS Code: |
| 84 | + |
| 85 | +* Right-click on a project node in the Projects Explorer and select the `Delete Project` menu option. |
| 86 | +* Open the command palette and run the `ObjectScript: Delete Project` command. |
| 87 | + |
| 88 | +{: #server-side} |
| 89 | +## Editing Project Contents Server-Side |
| 90 | + |
| 91 | +There are a few methods to create a workspace folder to view or edit documents in a project directly on the server: |
| 92 | + |
| 93 | +* Follow the steps [here](../serverside/#config-server-side) and select the project. |
| 94 | +* Right-click in the [Explorer view](../extensionui/#explorer-view) and select the `Add Server Namespace to Workspace` menu option. |
| 95 | +* Use the InterSystems Tools view, as described [here](../extensionui/#viewing-and-editing-source-code-on-the-server). |
| 96 | +* Right-click on a project node in the [Projects Explorer](../projects/#explorer) and select the `Add Workspace Folder For Project` menu option. |
| 97 | +* Add a folder to your `.code-workspace` file directly: |
| 98 | +```json |
| 99 | +{ |
| 100 | + "uri": "isfs://myserver:user/?project=prjname", |
| 101 | + "name": "prjname" |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +{: #client-side} |
| 106 | +## Editing Project Contents Client-Side |
| 107 | + |
| 108 | +The entire contents of the project can be easily exported to your local file system for client-side editing. To do so, simply right-click on the project you'd like to export and select the `Export Project Contents` menu option. |
| 109 | + |
| 110 | +## Notes |
| 111 | + |
| 112 | +If you are getting `ERROR #5540: SQLCODE: -99 Message: User abc is not privileged for the operation` when you try to expand the Projects Explorer or view a project's contents in a virtual folder, then grant user abc (or a SQL role they hold) the following SQL permissions: |
| 113 | + |
| 114 | +```SQL |
| 115 | +GRANT SELECT, INSERT, UPDATE, DELETE ON %Studio.Project, %Studio.ProjectItem TO abc |
| 116 | +GRANT EXECUTE ON %Studio.Project_ProjectItemsList TO abc |
| 117 | +``` |
0 commit comments