Using Visual SourceSafe for ASP.NET—Start to Finish

Paul Sheriff and Michael Krasowski
PDSA, Inc.

December 2003

Summary: Walks through the complete process of managing your ASP.NET projects using Microsoft Visual SourceSafe. (17 printed pages)

Applies to
   Microsoft® ASP.NET
   Microsoft® Visual SourceSafe®

Why Source-Code Control
Isolated vs. Non-Isolated Mode
Set Up Your SourceSafe Database
Adding Your ASP.NET Solution to VSS
Manipulating Files with VSS
Tracking the History of Files
Use Labeling for Your Versions of Software
Retrieving Solutions from Visual Studio .NET
Conclusion

Some developers believe that source-code control is a necessary evil. Yet, source-code control is a sound business practice supporting your software development process. In this article you will be shown a real-world step-by-step approach to effectively using Microsoft® Visual SourceSafe® as your source-code control mechanism. You will be shown how to create a new SourceSafe database, how to check in and check out files, and how to create releases using labels.

From a simplistic perspective, a Software Configuration Management (SCM) product, like Visual SourceSafe (VSS), is a central library, or database, of documents that make up a project. Visual SourceSafe can store any stream of bits, such as project plans, specification documents, database objects, source code, and any other artifacts of your project. As a best practice, all project artifacts, not just source code, should be contained in a Visual SourceSafe database for easy access, sharing among team members, and most importantly, for version control.

As in any library, the ability to "check out" a file for use is necessary. By checking out a file, a user can edit the file. Typically, only one person can check out and edit a file at a time. As a best practice, ensure that only ONE person can ever have a file checked out. In our research for this article, we reviewed some white papers that offered scenarios of Visual SourceSafe use recommending that multiple users could check out the same file. They recommended that all changes could then be merged back together. While this may appear somewhat easy to do using the tools built into VSS, in actual practice it has several drawbacks. It takes longer to check items back in, could lead to someone having to manually check conflicts in the merge process, does not generally work with binary artifacts such as databases, Microsoft® Word documents, and so on, and does not always reflect the accurate history of who updated what and when.

VSS allows the administrator of the library to define its access control. Users are given access IDs and passwords, plus access rights. Access rights may be as simple as read or read/write capabilities, or as complicated as functional rights. A functional right, for example, is the ability to delete files.

Knowing what has happened to each and every file (source code, project plans, requirements, and so on) through its lifecycle is a very important feature. VSS keeps a history of all activity, such as when a file was created and by whom, each revision to that file, notes or comments about that file, and other information to help you track the lifecycle of that document.

The VSS features mentioned above, and many more, allow you to effectively manage the development, build, and maintenance process in a structured, well-managed approach. These are just some of the reasons why the use of VSS will help make your software development much more productive.

There are a couple of different models you can choose when developing Web applications in a team environment. The first approach, non-isolated, is to have every developer creating and modifying all files on a central server. Non-isolated development has you use one Microsoft® Internet Information Services (IIS) server on a centrally shared computer and all the files for your application reside within a virtual directory on that server. All developers would check out files from VSS and those files would be put into the virtual directory on the central IIS server.

The Isolated approach to Web development is to have each developer create a virtual directory within the IIS running on their own development computer. The isolated approach will have each developer retrieve or check out files from the central VSS database and onto their local machine. The developer will edit, debug, and test everything on their local machine, and once everything is working, they can then check the file(s) back into the central location for other developers to retrieve.

Each of these two types of development has their pros and cons. Let's examine their advantages and the disadvantages.

• Developers do not have to have IIS running on their local computer.
• All the source code is in one location, not spread out on different developers' computers. If you lose that one computer, and have not checked the changes into SourceSafe, you could potentially lose those changes.

• It is very easy to inadvertently affect another developer's work.
• When one developer runs an application with debugging, it locks the process so other developers cannot debug their application at the same time.
• If developers do work on the same file, then the "last check-in wins."
• Offers limited source control capabilities.
• If a developer modifies some code that causes the code not to work, everyone else will no longer be able to run that part of the project.

• You can both develop and debug the application without inadvertently interfering with other developers.
• You can test out changes locally without affecting other developers.
• It provides superior support for source-code control.
• Developers can move the project to another machine and take it with them to show users without having a network connection.

• Each developer must set up IIS on their local computer for developing Web applications.
• Each developer must remember to check all their files back in prior to leaving for the evening to ensure that the files are backed up—assuming the VSS library is part of a backup process.

Our recommendation is to use the isolated model for development. Of course this means each user must have IIS on their machine, which in some organizations can be restricted, but it is by far the best model for the most flexible source-code control.

Be sure you set the right options in Microsoft® Visual Studio® .NET so you can use the isolated model. From within Visual Studio .NET, go to the Tools | Options tab and click File share and not the option for Microsoft® FrontPage® Extensions. The FrontPage Extensions option is what you would use if you are using a non-isolated approach with all files located on a central server.

Now that you have a good overview of Visual SourceSafe and understand the benefits of using it, let's learn how to get started. The first step is to identify a location for your centralized VSS database. The database is not a database in the strict sense of the word. It is simply a folder on a hard drive. This folder should be placed onto a network share where all developers can locate it. If you are a single developer, this could even be put onto your local hard drive.

If you have not already done so, install the VSS Administration tools from your VSS CD. You need to choose these options through the custom install. On the CDD you will typically run the ACMBoot.exe to allow you to install the Administration tools. Under the Custom options for the install, you will need to choose Administrative Programs and Create SourceSafe Database options.

After installing the Administrative programs, you may now go to your Start menu. Click Programs | Microsoft Visual SourceSafe | Visual SourceSafe 6.0 Admin. This will launch an interface from which you can click Tools | Create Database... . You will see a dialog box that looks like Figure 1. Type in the location where you wish to create this new SourceSafe database, such as "D:\MyVSSDB" or \\SharedDrive\MyVSSDB.

Figure 1. Specify the location of a shared folder to be used for all your SourceSafe files.

After the database is created, you will see a dialog that looks like Figure 2. This is just a warning that when this SourceSafe database is created, the Admin user that is created has no password associated with it. Be sure to assign a password to the Admin user by clicking on the Admin user and clicking Users | Change Password... from the menu.

Figure 2. Secure your Administration tool by assigning a password to the Admin user.

After you have created the database, you will now be in the Visual SourceSafe Administrator tool (Figure 3). This tool only allows you to connect up to one VSS database at a time. You must create all the users in this database that will be allowed to check out and check in files from this database. For each database that you create, you will need to add the appropriate users. This is a nice feature in that only the users that you set up are allowed into this database; however, if you have multiple VSS databases that you wish to grant all users access to, you will need to set up each user individually in each database.

Figure 3. The Administrator tools allow you to create new users, create databases, lock databases, and perform other system administration functions for SourceSafe.

You should now add yourself as a new user to this database. Make sure you use your domain logon ID (without the domain name) as the user name in SourceSafe. SourceSafe will pick up your domain logon ID and attempt to use it to log on without prompting you. If you assign a password to this VSS database, again, make sure it matches your domain password.

Remember the location of this new database; once you've added users with their domain names to the database, you will need to tell everyone where it is so they can locate it when they first set up their VSS client utility.

Now that you have created a VSS database, you can add projects and project artifacts to this database. There are a couple of different methods you can use to manipulate this VSS database. You can use the VSS Explorer tool. This tool is useful for adding the "other project artifacts" to your database. You can also use VSS from within Visual Studio .NET. In fact, for adding new projects to VSS, it is recommended that you use Visual Studio .NET to add them. Using the Visual Studio .NET interface will add some binding information to your .SLN file so other developers can get hooked up to VSS automatically upon getting the solution from VSS.

Note For this article I am using the Microsoft® ASP.NET Portal Starter Kit available from the ASP.NET site as an example of checking files in and out. Feel free to use whatever project you wish.

Assuming that you have downloaded and installed the ASP.NET Portal Starter Kit, you will now learn how to add this solution to VSS. With the solution open in Visual Studio .NET, select File | Source Control | Add Solution to Source Control... from the menus as shown in Figure 4.

Figure 4. Add solutions to SourceSafe using the menus built into Visual Studio .NET.

After selecting this menu item, you will most likely get the dialog shown in Figure 5. If you are using the isolated development mode, this just means that you will now reference all your files using normal file URLs instead of FrontPage Server Extensions. Go ahead and click the check box Don't' show this dialog box again (Always allow addition of Web projects using File Share access to source control), and then click Continue.

Figure 5. Switching from FrontPage Server extensions to using file share access

You will now be prompted for your logon ID and password (see Figure 6) that you created when you set up your VSS database. Type in JohnD (or whatever you used) and any password that you set up. You will then need to click Browse... to locate the specific folder where you created your VSS database. When you are finished, click OK.

Figure 6.VSS logon

Visual SourceSafe will now prompt you for the project name to create in the database. This first dialog, Figure 7, "Add to SourceSafe Project," will refer to the Visual Studio .NET project where the solution file resides. Enter the name for this project such as, ASP.NET Portal Starter Kit (VBVS).

Figure 7. Give your project a name that will make it easy for you and other developers to locate later on.

VSS will prompt you for each and every Visual Studio .NET project in your solution. VSS will automatically add each Visual Studio .NET project name into the textbox in the Add to SourceSafe Project dialog box as shown in Figure 8. In this case, the second prompt will be PortalVBVS. Be sure to click the folder, "ASP.NET Portal Starter Kit (VBVS)" to place this project under this solution.

Figure 8. Add each new project to VSS individually.

VSS will warn you that the solution file is located in the same folder as the project. This is exactly what you want to do, so go ahead and click the check box and continue on. You may or may not get the dialog shown in Figure 9. If you do, go ahead and check the check box and click OK. This just means that you are aware you have other items in the folder that are not a part of the project file and therefore will need to be added manually through the VSS Explorer tool. This might include documents or .SQL files that are in your folder but are now specified in the project file.

Figure 9. If you have more files or folders that are not referenced in your project file, you will be informed of this by VSS.

Now that your solution and your projects have been placed under SourceSafe control you will see that Visual Studio .NET now uses special icons to show whether the file is locked or checked in as shown in Figure 10. Visual Studio .NET will display a lock icon next to each file under source-code control. You will see a check mark next to any file checked out to you, and a circle icon when a file is checked out by another user.

Figure 10. Visual Studio .NET displays the status of each file under source-code control.

To view the complete project within the VSS database, select Start | All Programs | Microsoft Visual SourceSafe | Microsoft Visual SourceSafe 6.0 from your operating system menu. You may be prompted to log on again. Go ahead and enter your logon name and password. If this is the first time running the VSS Explorer (see Figure 11), you may also need to locate the VSS database by browsing for the folder where you created the database.

Figure 11. The Visual SourceSafe Explorer allows you to view the complete project and all of the files that have been placed under source-code control.

Once you have placed your project files into the VSS database, you will find that all of the files in your project are now set to Read Only on your disk. You can still run your solution with files that are not checked out. But you will need to check files out to work on them within Visual Studio .NET. While this is an extra step compared to what you are doing now, the payoff is the ability to go back to a previous version, and avoid stomping on a file another developer may be modifying at the same time.

When it is time to check out a file to work on it, you simply need to right-click on that file in the Solution Explorer window and click Check Out... from the context-sensitive menu. For example, in the Portal Starter Kit, click the Default.aspx file, right-click, and click Check Out... You should see a dialog that looks like Figure 12. Click the Check Out button to check out not only the .ASPX file, but also the .ASPX.resx and the .ASPX.VB file. Now you can work on that file, and other users will see that the file is checked out.

Figure 12. The Check Out dialog allows you to retrieve one or many project files and make them writable on your hard drive.

After you have made all the modifications you wish to the file(s) you have checked out, you need to check them back into SourceSafe. There are a couple of things to keep in mind when checking in files. First, make sure that any changes you made to any pages or classes in your project compile. If you do not, then any other developer that retrieves the latest changes from the SourceSafe database will get errors in their project. This is not cool. Also, you should be diligent about checking in your files at the end of each day. This ensures that your files are backed up into another location, and not just sitting on your hard drive; any changes you have made are preserved in case your hard drive crashes. If you are at the end of the day and your source code does not yet compile, simply comment out the offending code and then check it in.

If you are working within a team environment, you have other developers modifying other files within the project. At some point you will want to synchronize your project with all of the latest changes that are in the VSS database. To do so you will click on the project in the Visual Studio .NET Solution Explorer window, right-click and then click Get Latest Version (Recursive). This will go to the VSS database and retrieve any changed files and bring them into your project. You can now run the project locally on your machine and see all the changes that other developers have made.

At some point the development team will reach the point where they wish to create a "build," "version," or "release." VSS uses version numbers to keep track of every change you make to your files and projects. This gives you the ability to retrieve any version of a file or project. VSS keeps track of old versions in three ways: by internal version number, by date, and by user-defined labels. For your own versioning, you will use the user-defined labels, not the internal version numbers assigned by VSS.

VSS maintains an internal version number for each file that is checked in. Each time you check a file out, make any changes to it, and then check it back into VSS, a new number is created for this version of the file. You can view the complete history of a file by using the History dialog in VSS. There are two methods to view this dialog; through Visual Studio .NET and through the VSS Explorer tool.

From within Visual Studio .NET, click the file for which you wish to view the history, for example, default.aspx. Next click File | Source Code Control | History from the Visual Studio .NET menu system. You should now see a dialog box that looks like Figure 13. If you have not yet made any changes to the default.aspx file, then you may not have any versions other than the first one.

If you bring up the VSS Explorer tool, you can locate a specific file in the explorer, right-click on it, and click the Show History... menu item to display this same dialog box.

Figure 2. VSS Explorer shows the complete history of a file.

Note The internal VSS version numbers are for reference only and do not directly relate to your build or version number. For this you will use Labeling (discussed below).

Instead of relying on these internal version numbers that SourceSafe assigns to files, you will most likely want to create your own "label" for a set of code that defines a release for your software. A release could be your first beta milestone, your first version of the product, an incremental release, or the second, or third release of a product.
Each file will get its own internal version number, and depending on how often a file is modified, these numbers will never match up across a whole project. So instead you can apply your own label to a complete project to identify all of the files checked in at the point in time when you create this label.

You might create a label (up to 31 characters) with the text: "1.0," "2.01b," "Final Beta," or "Approved for QA." After you apply a label, you can retrieve all the files associated with this label from the History dialog box. While individual files can be labeled, you will most likely find that you will apply labels at the project level. When you label a project with a descriptive text string, all the files in that project and subproject inherit the label.

You may label a project at any point in your development cycle. For example, with each "release" of your product, whether in alpha, beta, or final production code, you will most likely wish to place a label on all of the project artifacts at that time. As you continue to develop, if you ever need to get the source code from beta 1.0, then you can do that. You can rename labels if you wish, without affecting any of the source files.

To create a label, click the Project folder in the VSS Explorer tool that you wish to label. Click File | Label... from the menu, and you will see a dialog as shown in Figure 14. After entering a descriptive label name and a comment telling what this label is used for, click OK to apply the label to this project and all files and subfolders under this project.

Figure 14. Using the VSS Explorer tool to create a label

If you select the project again in VSS Explorer, right-click and then click the Show History... menu item to display the History dialog, you will see the label as shown in Figure 15.

Figure 15. The History dialog in VSS Explorer allows you to see the different labels you have applied.

There may be cases where you have labeled a version and at a later point realize that you forgot a file that should have been a part of that labeled version. To add a file and make it a part of a label, simply add the file to your project. Click that file in VSS Explorer and then click File | Label... and assign the same label as you labeled the project. When you retrieve files based on a label, it will get this file as well, since it has the same label name. Make sure you get the spelling exactly right.

To retrieve all the files associated with a specified label, you "get" those files. That is, you will not be able to check out the files that are under a specific label, but you can retrieve them. To do this, right-click the project whose contents you wish to retrieve in VSS Explorer, and click Show History.... When the Project History Options dialog appears (see Figure 16), check the Labels Only check box and click OK.

Figure 16. Retrieving the labels for a project

At this point you will be shown all of the labels you have assigned to the project selected. Click the label you wish to retrieve and then click Get on the right hand side of the screen (see Figure 15). This will cause all of the files with this label to be copied to the working directory assigned to this project. As mentioned, you will not be able to check out any files from a labeled release. This prevents anyone from tampering with that released set of files.

Once your project lead has created the initial solution for the application you are building, you will want other developers to be able to retrieve this solution and set it up on their computers. You do not want each developer to have to recreate the virtual directory on their computer and ensure that all of the files get into the proper locations. Luckily, VSS and Visual Studio .NET will take care of this for you.

Visual Studio .NET integrated with VSS will create the appropriate folders on your hard drive for you, create a new virtual directory, and copy the files down from VSS into the new folders for you. You should make sure you always do this process through Visual Studio .NET and not through VSS. Otherwise you will have to manually configure IIS and set references to the VSS database yourself.

To follow the next steps, you will need to be a developer on another machine (or you need to wipe out the virtual directory you created earlier). Open a new instance of Visual Studio .NET. Click File | Source Control | Open from Source Control... and you will see a dialog as shown in Figure 17. Click the PortalVBVS project in the window. Type in a different folder name in the Create a new project in the Folder text box and click OK.

Figure 17. Retrieving a SourceSafe project into a new folder

If you choose a folder that does not exist on your drive (and it shouldn't) you will be prompted to create the folder. Click Yes All to create all folders necessary for this project.

Next you will be prompted for the virtual directory under which you wish to place this project, as shown in Figure 18.

Figure 18. Assigning a virtual directory to the project

Depending on how your project and solutions are laid out in SourceSafe, you may be prompted for the solution file to open. If so, choose the .SLN file from the dialog. With the Portal solution, the .SLN files are in their own separate folder, so SourceSafe might not prompt you.

Next, Visual Studio .NET will prompt you for the location in IIS where you wish to create this virtual directory. Enter the Web server name and virtual directory name and click OK.

Figure 19. Assigning the project to a Web server

Now Visual Studio .NET will start bringing down all of the files for this project. In the sample that is in this article, I used D:\PortalVBVS. This means the solution will be stored in this folder. All of the other files for this project are placed in whichever folder your default Web site is pointing to. This folder is usually c:\inetpub\wwwroot. The project is now set up on this other developer's machine and is ready to be used. They can simply select the start page for the site and press F5 to run the application. They can now start checking out files and work on them, and check them back in—all from within Visual Studio .NET.

Visual SourceSafe should be a part of every developer's routine and a team requirement for every development manager. Even if you are a single developer, effective use of this tool can help you ensure that a backup of your source code is on another machine, and allows you to go back to a previous version of your source code. Creating and using VSS is simple and easy; it just takes a little discipline to use it. With good source-code control, you will find that your development process will improve, and you will get all the other benefits of software configuration management.

Paul D. Sheriff is President of PDSA, Inc., which provides .NET consulting, products, and services, including an SDLC document and architectural framework (www.pdsa.com). Paul is Microsoft Regional Director for Southern California. His .NET books include ASP.NET Developer's Jumpstart (Addison-Wesley) and several eBooks listed on PDSA's Web site. Reach Paul at PSheriff@pdsa.com.

Michael Krasowski is Vice President of Development for PDSA, Inc. Previous to this position, he was Senior Manager of Information Technology for The Boeing Company, Long Beach Division. He has over 27 years of IT experience and teaches .NET at the University of California, Irvine extension program. Reach Michael at Michaelk@pdsa.com.

© Microsoft Corporation. All rights reserved.