Using Visual Sourcesafe
[The following tutorial was something I knocked up for myself and my work colleagues, when we developed a need for a source control system. Clearly VSS is not the best ever source control system, but the integration with Visual Studio is very useful.]
Visual SourceSafe (VSS) is a client/server application which acts as a storage system for files. A file stored in a VSS server is not available via the standard file system, instead, it must be accessed through the VSS client tools - the VSS windows client, the VSS command-line tool, or else some application which integrates with or emulates these client tools.
The following discussion refers to version 6.0d. It contains three types of section:
- Discussions of important concepts, headed like this.
- Walk-throughs of development scenarios, headed like this.
- Practical advice and best-practice, which...
...appears in shaded boxes.
VSS Database
A VSS Database is a single instance of a VSS server - it's the big black box into which files get placed। All commands to VSS are directed towards a particular VSS Database, and wach database maintains a SRCSAFE।INI file which contains configuration information.
VSS Project
A VSS Database is organised as a tree structure, with each of the nodes of the tree being a VSS Project. Each database contains a single root project, which can branch (to a depth of 15 nodes) into sub-projects.
VSS Projects are misleadingly named; instead they should be thought of as directly analagous to filesystem directories, being unordered collections of up to 8000 files of any type. To illustrate this, note that where an application's source-code is organised into files that live in subdirectories off the main directory, these subdirectories have to be mapped onto subprojects of the application's main project directory.
Don't confuse Visual Studio 'projects' with Visual Sourcesafe 'projects'. The latter are more like directories, or folders. In fact, if you just think Visual Sourcesafe 'folder' where the documentation says Visual Sourcesafe 'project', it will be easier to follow.
Working Folder
Because the files stored in VSS are not directly exposed as files, development work on these files takes place on local copies, which are first checked out of VSS, changed, then checked in again. While a file is checked out of VSS, it is can be locked to other developers, preventing file overwriting. VSS also retains historical information about a file's changes, so it is possible to extract and use old versions of a file, or roll back unsuccessful changes.
The folder in which a user manipulates his local copy of VSS project files is known as his 'working folder'. Each user will often have a distinct, local working folder for each VSS project, the details of which are held by the VSS client in its SS.INI file.
Each working folder also gets populated with a VSSVER.SCC file, which contains version information about the files in that folder. This allows VSS quickly to determine whether or not local files are synchronised with those stored in the VSS database.
If it is possible that the source-code for your application may contain hard-coded file paths, it is important that developers' working folders are at the same location. One way of doing this is to require each application's working folder to be at the root of a particular drive.
Building and Deployment
For non-web applications, their compilation and deployment is not under the control of VSS. The process that builds and deploys an application needn't integrate with VSS except to extract the latest instances of the files into a local directory where they can be manipulated as required.
For web applications, VSS does support a 'deploy' command. This copies a project's files onto a webserver, either directly or via FTP. However, for various reasons one might choose to use other methods of deployment with web applications.
Development Scenario: A
Let's consider the situation in which two developers, UserA and UserB have to cooperatively develop a non-web application, are coming completely fresh to VSS, and neither uses an IDE to create the application.
In this scenario we shall assume that each developer has a development machine, and that there is a development server which both of them can access. This gives us the following three computers: DevelopmentUserA; DevelopmentUserB; DevelopmentServer
The first thing that needs to be done is for a VSS database to be installed on DevelopmentServer, and the VSS client tools to be installed on the two development machines. It's useful to know that the installation of VSS on DevelopmentServer sets up a network share to the installation directory, and the VSS client tools are available for users to install from there (this has the additional benefit that the client tools are set up with the DevelopmentServer database as the default).
Next, the VSS database has to be set up with appropriate users. VSS handles its own authentication, rather than integrating with Windows authentication (though file access is still subject to NTFS permissions, of course), so it is necessary to set up individual accounts in VSS for the two users.
Next, the application development should start, and the application files should be added to the VSS database. We shall assume that these application files are stored on UserA's personal development computer.
The advice from those with experience of developing using VSS is that before adding files to the VSS database it is useful to progress the development to a stage where the general structure of the application and its source code is mostly settled. This is because the process of renaming and moving application files can raise various small problems.
As he is not using a VSS-integrated IDE, UserA will use the VSS client tool to add the application file to the database. To do this, he will need to point the client tool at the appropriate VSS database, which involves executing File -> Open SourceSafe Database and navigating to the SRCSAFE.INI file on DevelopmentServer.
After identifying the appropriate database, the following procedure will add all of the application source files to the database:
select the root project ($/)
execute File -> Add Files
navigate to the root directory of the application files (leaving the Relevant Masks at *.*) and press Add
add a descriptive comment, tick 'recursive', and press 'Add'
agree to make the source directory the 'working directory' for the current project.
Alternatively, the required files may be dragged and dropped from Windows Explorer to the appropriate VSS project. This takes you to point 4 above.
Once the files are in the VSS project, UserB will be able to view the project via the client tool. When he tries to access these files, he will be prompted to nominate a local working directory, and will be able to work on from that point.
Getting vs Checking Out
If you 'Get' a file / project (which you do using the client tools by right-clicking on the item and selecting 'Get Latest Version'), a read-only copy is placed into your working folder. Changes you make to this file cannot be subsequently uploaded to the VSS database.
On the other hand, when you 'Check out' a file / project (which you do analagously to 'getting' it), a writable copy is placed into your working folder. By default, this locks the file to other users, so that while they may 'Get' a copy of the file they cannot themselves check it out. Notice that when you check out (and check in), you have the option to add a comment. This is to help developers keep track of the file changes.
When either of these options is being applied to a project, the procedure can be applied recursively, so that it is applied to subprojects of the chosen project.
Checking In
When you've finished making changes to a checked-out file / project, then you can check it in again, which writes the file changes to the VSS database. This procedure is also effected in the client tools using a right-click menu.
By checking project files out and in using VSS, developers can avoid the situation in which one overwrites the changes made by another.
Note that there are a few restrictions on filenames in VSS; for instance, they cannot contain the dollar sign ($).
Development Scenario: B
Let's now consider the situation in which our two developers have to cooperatively develop a non-web application using Visual Studio .NET. In this case the VSS commands are integrated with the IDE.
The recommended structure for a .NET solution is to locate each project folder under the solution folder (which is not the default: often, you create a project along with its solution files, and the two go into the same directory). It is easy to get the recommended structure when creating the project – the important check box to tick when creating the solution / project is revealed by clicking More, and reads Create directory for solution. Otherwise, it is possible to set up a blank solution first and add the project into it.
Let's assume that the VSS database and the VSS users have been set up correctly. Then the process of uploading the Visual Studio solution and its projects (recall that VS projects are different kind of things to VSS projects) will go via:
File -> Source Control -> Add Solution To Source Control
or possibly
File -> Source Control -> Add Selected Projects To Source Control
This action will first prompt for a VSS database path and user credentials, then (recursively) add one or more project to the chosen VSS database. It is possible to see the files uploaded to the database via the VSS client tool (though we found it necessary to close and open up the tool in order to see the added project – the refresh command did not seem effective).
Initially, the project files are in their checked-in state, demonstrated by a small blue padlock on the left-hand side of their icons. As has been said previously, in this state the project files cannot be amended. So a user who wants to amend a file has either to explicitly check it out from Visual Studio using one of the many menus that support this functionality, or else just attempt to edit it, which brings up a dialogue that helps him check it out. The checked-out status of the file is indicated with a small red exclamation mark.
Note that the compiled project files do not get placed into the VSS database. The generation and storage of these executables lies outside the purview of VSS. Furthermore, there are a number of project files generated by Visual Studio which contain information specific to an individual user, and these are not added to VSS either; such files have the extensions .suo, .user or .webinfo.
This deals with how UserA adds a project to Visual Studio project to VSS, but then how does UserB then access this existing project? The required command is:
File -> Source Control -> Open From Source Control
This then brings up a VSS dialogue box with the contained projects. When the user selects the required project, he is asked to nominate a local directory, which is then set as the user's project working folder.
Historically, people have had problems when attempting to share solution files (*.sln). It may be easier for developers to maintain their own solution files, and just pull in the project from VSS.
SS.exe
VSS also makes available a command-line program SS.exe to support its various functions. The main use of this tool is to allow integration of VSS functions into applications which, unlike Visual Studio, aren't integrated with VSS out of the box.
According to the VSS documentation, SS.exe "is usually in the Win32 subfolder under the folder you choose in the setup program". In our case, it was found at:
[D:\Program Files\Microsoft Visual Studio\Common\VSS\win32\SS.exe]
If you are going to make extensive use of SS.exe, you'll probably want to add its containing directory to the environment PATH variable.
It may also be necessary / useful to add a couple of VSS-specific environment variables. The first, SSUSER, relates to VSS authentication. According to the documentation, when the command-line tool is used, VSS picks up the user's logon name and tries to authenticate using that (apparently ignoring the password, which makes you wonder why it's there at all). If the VSS username is not the same as one's NT logon name, however, one can put the VSS username in the SSUSER environment variable, and this is used instead (again, without any password).
Note that in order to access the VSS database in the first place, users will have to have an NT login with appropriate access permissions. The authentication provided by VSS lives on top of standard Windows security.
The second environment variable, SSDIR, is used to inform SS.exe which VSS database it should use. If you install the client tools via the executable provided on the server hosting the database, then this may be set automatically to point to that database. Otherwise, you will probably need to set it up automatically. In our case the setting looks like:
SSDIR = \\nwk-s-web\sourcesafe\
Development Scenario: C
Let's consider the situation in which two developers are using a basic development tool like Textpad to develop a non-web application. One way in which they could proceed is to use the VSS client tool to check files in and out. But a prefered alternative might be to write a macro (or possibly, for Textpad, a 'user defined tool') utilising SS.exe.
There is no point in going through exactly how this is done in Textpad. Instead we'll take a quick look at the kind of SS.exe commands that would be used.
First, we should note that the command-line tool is able to keep track of the 'current project' across commands (recall that for VSS a project is an element in a hierarchy). The following command sets this current project to 'tempProject.root' - note the dollar sign and the forward slash in the code (the latter of which indicates that tempProject.root is itself located at the database root).
ss cp $/tempProject.root
The following command checks out the file tempProject.sln from VSS:
ss Checkout $tempProject/tempProject.sln
There are two important points to note about this. Firstly, we are identifying the file we want by providing a virtual path. Because we previously set the current project to be equal to
$/tempProject.root
the virtual path resolves – in the familiar way – to
$/tempProject.root/tempProject/tempProject.sln
The second point is that the command does not place the checked out files in any working folder that might have previously been specified for this project. Instead it places the files in the folder in which the user executes the command.
We can also check out project files recursively, which creates the appropriate local subfolders. For example, the following command (which uses an absolute project path) checks out all of project and subproject files under tempProject.root:
ss Checkout $/tempProject -R
(For some reason, if you don't provide the project / file path in the Checkout command it asks you to enter one, but then takes the current project setting if you press enter.)
Checking files in works in an analagous way, but uses the 'Checkin' command, eg.
ss Checkin -R
Getting (recursively) the latest version of project files is equally straightforward:
ss Get -R
Multiple Checkouts
By default, if you check out a file then no other user can check it out until you've checked it back in: the file becomes locked to changes by anyone other than you. But the VSS administrator may enable 'multiple checkouts', which (fairly obviously) allows multiple users simultaneously to check out files.
So, what happens when UserA and UserB each checks out a file to his local working folder, each updates it independently, and then each tries in turn to check it back in? What needs to be avoided here, obviously, is UserA's changes being overwritten by UserB's check-in. What VSS tries to do is to merge each user's changes into the master copy. This is easiest if users have made small changes to different parts of the file. However, if users have each changed the same part of the file then merging is not possible, so VSS rejects UserB's check-in attempt, with appropriate information about the problem, and requires him to resolve the conflict.
The people that I've talked to about this, who have been using VSS from its earliest versions, recommend against using multiple checkouts. They claim that the merging algorithm isn't 100% solid, and that there are management benefits to knowing exactly who is currently working on a file. However, it may be that where development involves a large, geographically distributed group of people that communication problems would offset any problems with multiple checkouts.
Web Deployment Models for VS.NET
The MSDN article Web Projects and Source Control Integration in Visual Studio.NET provides three useful models for collaboratively developing websites (in VS.NET, but the models are useful beyond this). The models differ crucially in where each developer can run and test changes. In each case the deployment of the production website from a latest version is independent of the model. - Isolated Development
In this model, all developers maintain a working copy of the website on their own development machine (which must therefore be running web server software). Latest versions of the code can be brought down from VSS in the familiar way. This is the recommended development model.
- Semi-Isolated Development
In this model, all developers share a single development web server, such that each has a distinct working folder on that server. While users share a webserver, therefore, each user maintains his own copy of the web application. Latest versions of the code are brought down from VSS to these working folders.
One of the disadvantages of this model is that the debugging process freezes all the applications on the website, so at most one user can test / debug at a time.
- Non-Isolated Development
In this model, there is a single development web server, but developers must access the master copy of the code using Frontpage Extensions. Here developers both share a webserver and share a copy of the web application (although they may be able to download the files to local machines, when the developers run and test changes they are using the same code). In order for there to be VSS integration, the website needs to be a Frontpage web project (which can be set to integrate with VSS).
Development Scenario: D
Let's look at the situation where our two developers are creating a simple ASP.NET website with VS.NET. I shall assume that they use the 'isolated' development model.
When you create a new ASP.NET web application in VS.NET, the default location for the project files lies somewhere under the root folder of the default website, which will probably be something like this:
C:\inetpub\wwwroot
On the other hand, the location of the solution file is likely to be elsewhere. But Microsoft recommends that the solution file should be stored in a folder above the root project folder. The way round this problem is to create a blank solution located at a certain folder, then map a folder below it as a new virtual IIS directory, and use this virtual directory as the location for the web application.
So, let us suppose that DevelopmentUser A starts off by creating a blank solution, locating it at:
C:\Solutions\TestSolution1
He then creates a new folder
C:\Solutions\TestSolution1\TestProject1
maps this to the IIS virtual directory
http://localhost/TestProject1
and creates the new project TestProject1, locating it in this virtual directory.
To add this to VSS, DevelopmentUserA uses the standard command:
File -> Source Control -> Add Solution To Source Control
DevelopmentUserA ignores the warning that he will no longer be able to open the project using FrontPage Web access - accessing web projects using File Access is preferable where this is possible (basically this means that VS.NET just accesses the project files using the file system, rather than getting them from IIS via Frontpage Extensions). In the next dialogue boxes he enters the appropriate credentials to place the solution in the VSS database with the appropriate name, and the job is done.
According to the Microsoft document Team Development with Visual Studio.NET and Visual SourceSafe, the project structure in VSS should mirror the file structure in the working folder. But VS.NET seems very keen to place solution files in VSS projects parallel to those containing VS.NET project files. It is possible to manually move these folders in VSS, and then tell VS.NET about the move, but it's not clear why this is important. Web Projects
VSS distinguishes between standard and 'web' projects. For the latter it has introduced – albeit in a fairly half-hearted way – some specific tools. So, for instance, there is a facility to create a site map, hyperlink checking, and some keyword expansion. Furthermore, there is also a 'deploy' command, which seems just to copy all the project files to location via FTP.
Sharing and Branching Files
It is possible to 'share' files between projects, so that there is a single master copy which appears in different places in the VSS project tree structure. Changes made to this copy from within one project will be seen in the other projects that share the file.
Right-clicking on a folder within VSS Explorer, or using the File -> Source Control menu VS.NET brings up the Share dialogue, from which one can choose files to share.
I have been informed that sharing of files can cause problems. In particular, the following scenario: a file is shared between projects A and B. It is checked out as part of project A but then by mistake checked back in as part of project B. (Exactly what problems this caused was left unspecified by my correspondant, but they seemed severe enough to warrant a warning).
Rolling Back
VSS maintains a history of changes to files, so that it is possible to roll back files to previous versions. From VSS Explorer you right-click the file and choose 'History', from which you can see a history of changes to the file along with possible actions. From VS.NET you use the File -> Source Control menu.
It doesn't look like it's possible to roll a whole project back to a previously known good point, however.
By default, rolling back a file erases all of the file history past that point. However, it is possible to perform a 'virtual rollback', in which the file history is not deleted.
Where files are shared between projects, rolling back a file from one project will result in the files branching.
Showing Differences
The VSS client tool is able to display the differences between different versions of text files, which can be useful for debugging purposes.
Pinning
It is possible to pin files so that they can't be changed (at least without first being unpinned).
Labelling
As well as commenting actions, users can add labels to files or projects. In the VSS client tool this is effected by right clicking or using File -> Label…
Labelling files is useful for marking certain versions as important. For instance, a project might be labelled as 'Release Candidate 1', and if one wanted to extract that version at a later date, then one could look for the label. Note that when a label is applied to an object, a separate entry is created within the history of that object.
Cloaking
Where an operation like 'Get' is used recursively, the operation is applied to all of the subprojects (in this case we can say that it is applied 'indirectly'). If a user wishes to turn this behaviour off for his own recursive operations, he can mark the subproject as 'cloaked'. Subprojects so marked won't have operations applied to them indirectly. They may still be usable directly, however.
Shadow Folders
A shadow folder is a nominated file directory which is kept up to date with copies of the most recent files in a VSS project, the idea being that this folder can be used to compile latest versions of code. Unfortunately, however, the updating process is not recursive.