From Seapine Labs
[edit] Background
This example uses a solution that contains one project that is not associated with a source code control application and has not been added to Surround SCM. The solution only contains this one C# project.
Figure 1 shows the solution and project in the Visual Studio 2008 solution explorer.
Figure 1: Solution Explorer
As shown in Figure 2, the solution is located in the C:\Projects\Dev\VS08INT\ folder.
Figure 2: Project Location
[edit] Choosing the right plug-in
In Visual Studio, under Tools > Options > Source Control > Plug-in selection you will see two options for Surround SCM, as illustrated in figure 3.
Figure 3 - Plug-in selection window
So which one should you choose and why? To answer this qusetion, it is best to first give a quick explanation of each one.
The Surround SCM option uses the plug-in built using the MSSCCI API, which was designed to provide very basic version control features to allow source control providers IDE integration. While this plug-in offers you most of Surround SCM's features, it is limited. This is the interface that has been available in all version of Visual Studio.
The Surround SCM Integration Provider option uses the plug-in built using the new VSIP API. This new API allows us more control and gives us the ability to provide more functionality, like changelists and changing workflow states. This plug in is available only in Visual Studio 2005 and 2008.
This article explains how to use the Surround SCM Integration Provider plug-in. The Visual Studio 2005 Integration article uses the Surround SCM plug-in. The instructions for Visual Studio 2005 should be nearly identical to those in Visual Studio 2008.
[edit] Adding an Existing Solution to Surround SCM
The solution and project have to be added to Surround SCM before source control commands can be accessed. When you put a solution under source control you are prompted to automatically add all projects and files.
To add the solution to Surround SCM, open the Visual Studio solution and choose File > Surround SCM > Add Solution to Surround SCM....
At this point you may get the Surround SCM login window. If you have your client set to automatically log you in, then you will bypass this.
The Surround SCM Repository Browser window opens.
Surround SCM cannot establish an association because the solution has not been added to Surround SCM and the directory where the solution resides is not set as a working directory in Surround SCM.
You must associate the solution with a repository in a branch in Surround SCM. This is accomplished through the 'Surround SCM Repository Browser window, which is shown on figure 4 below.
Figure 4: Surround SCM Repository Browser
If you want to add the solution file to an existing repository, select the repository and change the working directory to be the directory where your solution file resides. Otherwise, select the branch and repository you want to be parent of the new repository. The new repository will contain the solution file. In this example, shown in Figure 5, the repository for the project is created on the mainline branch under the top-level repository. Click the Create Repository button after the branch and repository are selected.
Figure 5: Create Repository Dialog Box
Surround SCM creates a repository for each directory under the solution. In this example, Surround SCM creates a sub-repository because the project files reside in a directory uner the solution.
As the Figure 6 illustrates, the repository structure follows the same directory structure shown in Figure 2. Note that the bin and obj repositories are not created in Surround SCM because the files these directories contain are not supposed to be controlled.
Figure 6: Repository Structure
[edit] Accessing Surround SCM Commands in Visual Studio
Most Surround SCM commands can be accessed from a file's context menu, the Surround SCM menu or from the File > Surround SCM menu. The instructions below access the various commands from the Surround SCM menu. Figure 7 below illustrates the menu.
Figure 7: Surround SCM menu
For details on the Surround SCM command dialog options, please consult the Surround SCM user guide.
[edit] Getting the latest file version
Get Latest Version
You can automatically get the latest revision of selected files.
In the Solution Explorer, select the files you want to get. From the Surround SCM menu, select Get Latest Version. The latest version of all solution and project files are retrieved to the working directory.
Get...
Get files when you want to view a file but do not need to make any changes.
In the Solution Explorer, select the files you want to get. Choose Surround SCM > Get.... The Get dialog box opens.
To get an item, select the corresponding check box. If you do not want to get an item, clear the check box.
Click the Options button to access advanced get options.
Figure 8: Get Dialog in Visual Studio
The difference between Get... and Get Latest Version is that Get Latest Version will not show you a dialog box before retrieving the files.
[edit] Checking out files
Check out files when they need to be modified. To check out, select the file then choose Surround SCM > Check Out....
Figure 9: Check Out Dialog Box
Click the Options button to access advanced check out options.
(Note: The recursive check box is unavailable because it does not apply to check outs from the Visual Studio IDE.)
[edit] Undoing check out
If a file is checked out and modified, but then a decision
is made to not save the changes, the check out can be undone.
To undo a check out, select the file then choose Surround SCM > Undo Check Out....
Figure 10: Undo Check Out Dialog box
[edit] Checking in files
Changes that are made to files need to be checked in to the Surround SCM Server periodically. Simply saving the files does not automatically check in the files. Checking in the files creates a new version of the files and gives other users access to the changes.
To check in files from the Visual Studio IDE, select the files then choose Surround SCM > Check In....
Figure 13: Check In Files Dialog Box
Click the Options button to access advanced check in options.
[edit] Add to Label
You can add the files from the current solution to a label in Surround SCM. Select Surround SCM > Add to Label....
In versions of Surround SCM prior to 2009, the label menu is different.
[edit] View History
File history provides a way to view a source file’s history and work with a historical file version.
To view the history, select the file in the Solution Explorer then choose Surround SCM > View History.
[edit] Refreshing file status
You can query the server to get the latest status of each file. For example, if you check out a file from Surround SCM it will not be marked as checked out in Visual Studio until you refresh the status.
In the Solution Explorer, select the files you want to refresh then choose Surround SCM > Refresh Status.
[edit] Comparing file versions
You can compare the local copy of a file with the latest revision in Surround SCM.
In the Solution Explorer, select the file you want to compare then choose Surround SCM > Differences....
The differences utility starts if differences are found between the two file versions. For additional
information about the utility refer to the application’s documentation.
[edit] Merging
Modify a file in the solution by merging it with another one. You can then check in the merge result.
Select Surround SCM > Merge...
[edit] Changing Workflow State
You can change the workflow state of a file from Visual Studio. Note that the available states will depend on the current state of the file and workflow used in the repository associated with the file.
Select Surround SCM > Change State....
[edit] Viewing file properties
File properties include general and check out information.
To view properties, select the file in the Solution Explorer then choose Surround SCM > Surround SCM Properties.
[edit] Changelists
View your pending changelists from Visual Studio. Depending on the configuration of the server, you may also be able to view your committed changlists.
Select Surround SCM > View Changelists.
[edit] Open Project from Surround SCM
You can open a project from Surround SCM. Select Surround SCM > Open Project from Surround SCM.
The Surround SCM Repository Browser opens. Select the branch and repository where the project resides.
The project is opened.
[edit] Add Project from Surround SCM
You can add a project from Surround SCM to your existing solution.
Select Surround SCM > Add Project from Surround SCM.
The project is added to the current solution.
[edit] Bind/Unbind Settings...
You can modify the current bindings of the solution with Surround SCM.
Select Surround SCM > Bind/Unbind Settings....
The Surround SCM Connection Settings window opens, as illustrated in Figure 14 below.
Figure 14: Surround SCM Connection Settings
Select Disconnect to disconnect the connection to the Surround SCM server. The solution is still bound to the branch and repository.
Select unbind if you want to remove the association between a project or solution and the Surround SCM branch and repository. You must have a solution or repository selected in this window for the unbind option to be available.
If you select a project or solution that does not have any binding information, the bind button will be availab le.
[edit] Setting source control options
You can configure various source control options such as default check in options. Refer to the Visual Studio documentation for more information about the options you can set.
To set source control options, choose Tools > Options.
Figure 15: Visual Studio Options
Expand the Source Control category then select Environment to set the following options:
- Use...settings: Specifies the role you want to use.
- Get everything when a solution is opened: Automatically retrieves the latest revision of each file when a solution is opened. May be slow for large projects.
- Check in everything when closing a solution: Automatically checks in all files when a solution is closed. May be slow if you have a large number of files checked out.
- Display silent check out command in menus: Displays the Check Out Now command, which allows you to check out items without displaying the Check Out dialog box.
- Display silent check in command in menus: Displays the Check In Now command, which allows you to check in items without displaying the Check In dialog box.
- Keep items checked out when checking in: Checks in the changes but leaves the file checked out and writable.
- When checked in items are edited: Specifies what happens if you edit an item that is not checked out.
- Allow checked-in items to be edited: Specifies that checked in items can be edited. Editing checked in items can lead to data loss.
- When checked-in items are saved: Specifies what happens if you save an item that was not checked out.
Figure 16: Surround SCM Environment Options
Select the Plug-in Setting category to set provider-specific options.
- Use...settings: Specifies the role you want to use.
- Login ID: Specifies the Surround SCM username. This field is populated automatically.
Figure 17: Source Code Plug-in Options
[edit] Troubleshooting Visual Studio and Surround SCM integration
The following information is provided to help you troubleshoot common issues.
[edit] Surround SCM is not displayed as an active SCM provider
If Surround SCM is not available from the Source Control menu it is not configured as the active SCM provider. Check the following for possible causes and resolutions.
- The Surround SCM plug-in is not installed.
- Run the Surround SCM client installation and choose to install the Visual Studio Integration provider.
[edit] Add Solution to Surround SCM... is not an option under File > Surround SCM
You have selected Surround SCM Integratino Provider but when you select File > Surround SCM you do not see the option Add Solution to Surround SCM.... You can right click on the solution itself and see if the option is there. If not, you can instead select File > Surround SCM > Bind/Unbind Settings.... Click on Connect to login to Surround SCM, and then click on Bind. This will bring up the Surround SCM repository browser and allow you to bind the solution to Surround SCM.
[edit] Surround SCM files are not displayed correctly in Visual Studio
You added files to Surround SCM but the Surround SCM menu items are not enabled when the files are viewed from Visual Studio. Check the following for possible causes and resolutions.
- The Visual Studio project is configured incorrectly.
- Make sure the project points to a Surround SCM branch/repository that exists on the Surround SCM server you are connecting to. To check this information, open the project and solution files in Notepad and check the SCCProjectName value. The format is <branch>:<repository>. You can also use the Change Source Control command to check this information in Visual Studio.
- The branch/repository points to an invalid working directory.
- Make sure the working directory for the repository associated with the project points to the same local directory as the project. You may experience integration problems if you set up the working directory to point to a different location.
- The local .MySCMServerInfo file is out of sync.
- Visual Studio cannot determine where Surround SCM files are located if the .MySCMServerInfo file is out of sync. Go to the directory where the Surround SCM files are located and open the .MySCMServerInfo file with Notepad. Make sure it points to the correct branch/repository. If it does not, delete the file and refresh it from Visual Studio to regenerate it with the proper data.
- The files are above the solution in the local directory tree.
- Visual Studio does not support SCM integration with files that are not in or below the solution’s local directory tree. If the files are above the solution, create a new solution file at the top level of the source tree then add the projects to the new solution.
[edit] Files cannot be added to Surround SCM from Visual Studio
If files cannot be added to Surround SCM from Visual Studio, check the following for possible causes and resolutions.
- Check the Visual Studio Output window to view error messages.
- The Visual Studio Output window displays messages as Surround SCM actions are performed. Check this window for error messages that occur when you try to add files.
- The Visual Studio project is configured incorrectly.
- Make sure the project points to a Surround SCM branch/repository that exists on the Surround SCM Server you are connecting to. To check this information, open the project and solution files in Notepad and check the SCCProjectName value. The format is <branch>:<repository>.
- The Visual Studio project points to the wrong Surround SCM branch.
- This can occur if you maintain the Visual Studio project and solution files in Surround SCM then branch the repository that contains the files. After the repository is branched the local .MySCMServerInfo file still points to the old branch, which is where the files are being added. Configure Visual Studio to point to the correct branch then add the files to Surround SCM. Open the project and solution files in Notepad and change the SCCProjectName value to point to the correct branch. Then add the files to Surround SCM.
