Set up source control

You can perform Dimensions CM source control tasks from within Visual Studio. You can check out files and deliver your changes back to your Dimensions CM streams without leaving Visual Studio. This topic describes how to set up the Dimensions CM integration to Visual Studio.

Set source control provider and options

Set Dimensions CM as the source control provider and configure the options for Dimensions CM version.

To set Dimensions CM as the source control provider:

In Visual Studio, select Tools > Options. The Options dialog box opens.
In the left pane, select Source Control > Plugin Selection, and choose Dimensions Source Control.
Select Source Control > Dimensions Source Control in the left pane, and click the Version tab.
Click OK.

Share work areas with other Dimensions CM clients

When you open Dimensions CM projects and streams in Visual Studio, or add Visual Studio projects and solutions to Dimensions CM, you can set up a working location outside of your default Visual Studio folder that is compatible with all Dimensions CM clients.

When sharing work areas with Dimensions CM clients, you can open the same project in the desktop client or Windows Explorer, and update and check in updates from one common working location. This does not apply to working locations that reside under the Visual Studio default folder.

When using other clients to deliver new files that exist under the root of a controlled Visual Studio solution, the Visual Studio upload rules are applied. Make sure not to deliver any files in the solution that should not be controlled, for example:

Build artifacts, such as .obj, .dll, and .exe files.
User-specific Visual Studio control files, such as .suo and .csproj.user files.

The default exclusion filter for the Synchronization wizard excludes these files. If you have changed this filter or are using the command-line interface, ensure that only the necessary files are placed under Dimensions CM control.

Add solutions, projects, and files to source control

In Visual Studio IDE, you can add solutions, projects, and files to source control.

Guidelines:

You can add solutions that contain website projects to source control.
When adding a project or file to an existing solution or project that is already under source control you are prompted to check out the relevant files if pessimistic check-out is enabled. If pessimistic checkout is disabled, then when you save the solution or project, you are prompted to overwrite the existing read-only versions.
When adding a new Visual Studio project to an existing solution that is already under source control, exit Visual Studio and reopen the solution from source control. This ensures that the source control bindings and Dimensions CM metadata are set correctly.
The Dimensions CM item type PROJECT is reserved for project marker files. Any other files with the PROJECT item type are ignored.
Controlled solutions cannot span multiple Dimensions CM projects or streams.
Solutions must be contained in their own folder.
Solutions and projects should be in separate folders.
We recommend to keep only one solution in a folder.
For multiple solutions, we recommend a parallel structure so that solutions are contained in separate folders. In this layout, the solutions and projects on disk are peers rather than parents/children.
For multiple solutions that need to share projects, use a parallel structure. Keep project and solution folders separate, unlike in a parent/child layout.
You can add uncontrolled solutions with controlled projects to source control, provided that they are all in the same Dimensions CM project/stream, and that their repository path is the same as the path that would have resulted if the solution and projects were added in one operation. This is validated prior to attempting the operation, and you are notified if the paths are different.

After adding the solution to source control, reopen it from source control. This is necessary, as the Dimensions CM metadata for projects in the newly added solution does not match metadata for a solution controlled in one operation. When reopened, the solution behaves as if it was added in a single operation.
Adding Visual Studio solutions and projects to source control may fail if the Auto-Generate Item Identifier option is enabled in the Administration Console. In this case, the following error may occur:

You must not specify Item Id when creating Items of type PROJECT as this will be generated automatically.

To prevent this error, disable the Auto-Generate Item Identifier option in the Administration Console > Configuration Object Management > Object Type Definitions > Items. For details, see Set up the process model.

To add files to source control:

Choose what you want to add:

Action	Description
Add a solution and the projects within it to source control.	In Solution Explorer, right-click the solution and select Add Solution to Source Control. Or select File > Source Control > Add Solution to Source Control. If you are connected to Dimensions CM, you can right-click a favorite project.
Add a web project to source control.	In Solution Explorer, select a project (not the solution). Select Add Selected Projects to Source Control.
Add a project to source control without placing the solution under source control.	In Solution Explorer, right-click the project and select Add Project to Source Control. Within solutions that are not under source control, you can add only one project at a time.
Add new projects to source control when the solution is already under source control.	In Solution Explorer, select one or more projects. Right-click the projects and select Add Project to Source Control.

If you are adding a web project, a dialog box may open. Click Continue.
If your current Visual Studio session is not yet logged in to Dimensions CM, or if current connection is the not correct one for the solution that you are working in, you may need to supply login information for Dimensions CM.
If you are adding a solution or a project in an uncontrolled solution, the Select Dimensions Project or Stream dialog box is displayed.

Note: Your administrator can enable streams and/or projects. The following instructions apply to projects and streams.
Select the Dimensions CM project or stream to which you want to add the Visual Studio project or solution. You can also create a new stream or project. Click Next.

If you are adding a solution or a project in an uncontrolled solution, select a destination folder in the repository, or a work area. If you select a work area, choose from these options:

Option	Details
Create compatible work area	This is the default option for Visual Studio projects and solutions that reside outside of the default Visual Studio location. This option ensures that any Dimensions CM client may share the work area; for example, Visual Studio and the Desktop Client may update files in the work area. You can choose any folder between the root system folder and the source control binding root folder. We do not recommend choosing the root system folder. The binding root folder is typically at the root of the Visual Studio project and solution layout. In a hierarchical layout with a single solution at the root, the solution folder is the binding root. In a parallel layout with solutions and projects at the same level, the binding root is the top-level folder under which all solutions and project reside. For example, in this hierarchical layout: solution project1 project2 the solution folder is the binding root. In this parallel layout: root projects solutions the root folder is the binding root. The Selected Path setting is automatically set to reflect the correct offset from the location that you select. For example, if the solution file is under C:\Work\MyProjects\Solution1, and you select a work area path of C:\Work, then Selected Path is automatically set to the correct offset, \MyProjects\Solution1.
Create work area for Visual Studio only	If the solution or project is under the default Visual Studio location, this option is selected and you cannot change it. This work area is not compatible with other Dimensions CM clients.

Option

Details

Create compatible work area

This is the default option for Visual Studio projects and solutions that reside outside of the default Visual Studio location.

This option ensures that any Dimensions CM client may share the work area; for example, Visual Studio and the Desktop Client may update files in the work area.

You can choose any folder between the root system folder and the source control binding root folder. We do not recommend choosing the root system folder.

The binding root folder is typically at the root of the Visual Studio project and solution layout. In a hierarchical layout with a single solution at the root, the solution folder is the binding root. In a parallel layout with solutions and projects at the same level, the binding root is the top-level folder under which all solutions and project reside.

For example, in this hierarchical layout:

solution
project1
project2

the solution folder is the binding root.

In this parallel layout:

root
projects
solutions

the root folder is the binding root.

The Selected Path setting is automatically set to reflect the correct offset from the location that you select. For example, if the solution file is under C:\Work\MyProjects\Solution1, and you select a work area path of C:\Work, then Selected Path is automatically set to the correct offset, \MyProjects\Solution1.

Create work area for Visual Studio only

If the solution or project is under the default Visual Studio location, this option is selected and you cannot change it. This work area is not compatible with other Dimensions CM clients.

If the project or solution exists under a compatible work area (a work area that can be shared with other Dimensions CM clients), the wizard preselects a repository path to match the work area path. The Create compatible work area option is selected by default, and is the only available option.

A compatible work area root is either a folder set as default for the selected Dimensions CM project or stream, or it is based on Dimensions CM metadata that sets the work area root. Click Next.
(Optional) Select change requests to relate to the new files. You can select requests from your inbox or favorites. Click Next.
In the Select Design Part screen, you can select the design part to contain all new items you add. Your Dimensions CM administrator can guide you which design part to choose, if there is more than one. Click Next.
In the Options screen, enter a comment to apply to all the files you are adding. Dimensions CM stores it as the file description for each file. Click Next.
On the summary page, review the choices and click Upload. To change any of the settings, click Back.

After the solution or project and associated files are added to source control, source control icons are displayed next to each file. For example, locked files that are not currently checked out have a blue lock icon. Files that are checked out have a red check mark.

Open projects and streams from source control

After a project has been created and added to source control, you can access it by opening it from source control. This creates a copy of the project on your local system. You can then perform source control operations on it.

To open projects and streams from source control:

Use one of the following methods:

In Dimensions Explorer, expand Home and click Open From Source Control.
In Dimensions Explorer, expand a node with an open connection and click Open From Source Control.
In the Dimensions Project view, right-click a stream or project and select Open From Source Control.

Select a Visual Studio project or solution and click Next.
On the Select Location on Disk window, browse to select the location where you want to download the solution or project.

By default, Match the stream structure is selected. This option creates a work area compatible with other Dimensions CM clients at the selected location. The folder structure under this location matches that in the repository. If this option is not selected, then a relative work are that not compatible with other Dimensions CM clients is created. You can automatically create a folder named after the solution or project by selecting the Create directory with solution name option.

If the selected project has a default folder, the folder is suggested as the location, with a path matching the repository path. You can override this as needed. This location is the root folder under which the solution and projects are placed, in their correct relative hierarchy.

In the file system browser you can optionally create a new folder by clicking the New folder button.
Click Next.
Review the summary and click Download. To return to previous pages and make changes, click Back.

Save project references

When you add or modify references in a Visual Studio project, explicitly save the Visual Studio project to write the changes to disk.

You must save the project before performing any version control operations.

Restore source control bindings and features

You can restore the source control bindings to the solution.

If you encounter a crash in Visual Studio and find that the source control functionality is displayed to be lost after restarting Visual Studio, select the Set Repository Bindings menu option for the solution. This enables you to reinstate the source control bindings and re-enable source control functionality.

This option is also useful if you have downloaded a solution from the desktop or command-line client rather than from the Visual Studio client, and the repository bindings file (.cmscc) is not created.

You can use the Set Repository Bindings option on a controlled solution if it is opened from disk.

To determine the correct bindings, Dimensions CM detects that you are in the scope of a compatible work area root, and uses information from the project or stream from which the solution came.

Note: If you open a solution from source control outside of a compatible root work area, you cannot synchronize using the desktop client or the Synchronize wizard.

Attach to source control

If the opened solution is under Dimensions Control but does not contain the necessary bindings for the integration with Visual Studio, use the Attach to Source Control option.

This scenario is most likely when the solution has been added to Dimensions CM through one of the other clients as part of a bulk upload or migration activity. This wizard writes the necessary binding information into the solution and project files, and delivers these changes so that the solution can be treated as if it was added to source control through the Visual Studio integration.