In my previous post, I talked about how to make a copy of a VS.NET solution. However, I left off the details of the final step - adding the new solution back into VSS. This is probably the most basic process in working with VSS, but the details surrounding what happens behind the scenes can often leave a developer frustrated when they find that VSS did not organize the solution and projects in proper manner. In this post, I'll be discussing my experience with adding a solution to VSS in a manner that allows complete control over the finall VSS folder organization.
In my experience, I prefer to have my solution and project files organized in a single folder structure. I create a root level solution folder to contain my solution file, and each project would receive it's own subfolder in that root level solution folder. For example:
C:\...\MySolution
MySolution.sln
\MyProject1\
MyProject1.vbproj
MyClass1.vb
etc.
Creating a folder structure like this, in VSS, is not a straightforward process, despite the quick and simple menu items that VS.NET provides, for integration with VSS.
Assumptions
This entry assumes that you are using Visual Studio.NET 2003, and Visual SourceSafe 6.0d; and are familiar with Visual Studio.NET's basic functionality, menu system, and Visual SourceSafe's UI and "Working Folder" functionality.
The Process
The first step in organizing your solution file and project files in VSS, has nothing to do with VSS. The manner in which you create your inital VS.NET Solution and projects will greatly determine the resulting structure in VSS.
1) Create A Well Organized VS.NET Solution:
When creating a new project or solution in VS.NET, it is very easy to simply use the "File" menu to select "New" / "Project", select your project type, name, etc., and begin working with the default solution file that VS.NET creates for a new project. This approach, while quick and easy, will lead to some potentially unwanted results in VSS. You will end up with your solution file in the same folder as the original project that you create. Depending on the size of the solution (number of projects in the solution), this is probably not the desired outcome.
To create a new project that will be added to a solution and stored in VSS, always use the "File" menu to select "Blank Solution" in the "New" menu. When you give your solution a name, in this manner, VS.NET will create a folder for your solution and containing no other files. Create your new solution with a name that represents the overall solution being created, not just the initial project that will be added. This will help keep your solution files organized and makes it easy to remember which is which.
2) Add New Projects, One At A Time:
The next step is to add an actual project that can be compiled. To do this, I recommend right clicking on the solution file in VS.NET's solution explorer and using the "Add" menu to select "New Project". In the resulting pop-up window, you will be able to select any type of project that you need, giving it any name that you wish - no different than using the "File" / "New" / "Project" menu item mentioned above.
The key difference in this method is noted in the "Location" box. The default location for any new project that you add in this manner, should be a folder directly underneath of the solution file's folder. For example, if you created a solution named "MySolution", then your project's location would say something to the effect of "C:\...\Visual Studio Projects\MySolution\MyProject".
This is very important to note, as it will determine the flexibility of the folder structure created in VSS - whenever possible, always add your project files to a folder directly underneath of your solution file. (The only exception that I make to this rule, is a web project. All web projects need to be located in the root of your web server.)
3) Add Your Projects To VSS, One At A Time
This step is probably the second most important one, just behind step 1. In order to properly organize your solution in VSS, you do not start by adding your solution file to VSS. Always add your individual projects to VSS before adding the actual solution file. In VS.NET's solution explorer, click once on the first project in the solution. Then go to the "File" menu, "Source Control", and select "Add Selected Projects To Source Control...". If necessary, log into your VSS database to recieve the "Add To SourceSafe Project" pop-up window.
- Since this is the first project you are adding to VSS, you may not have a root folder setup for your solution. If this is the case, you may create a root level folder simply typing in the name of the folder you wish to create, in the "Project" text box. Click the "Create" button, ensuring that the root $ of VSS (or whatever folder you consider to be "root" in your scenario) is currently selected, and the folder will now appear in the list. Note: I would suggest copying the existing project name out of the Project box before typing in a root folder name.
- Now that there is a root folder to use, click once on that folder. If you had previously created a new root folder, paste the original project name back into the Project text box, ensuring that the root folder for your solution is selected in the folder list. Click the "OK" button and the project you currently have selected will be added to VSS, in the specified folder. It is not required to click the "Create" button at this point - clicking "OK" will prompt a confirmation to create the folder specified in the "Project" text box.
- Continue to add projects in the solution, to VSS, in this same manner - using the "Add Selected Projects To Source Control..." menu item, and selecting the root folder for your solution before clicking the "OK" button.
If all went well, you should end up with each of your projects in a subfolder of the root folder you created for your solution, in VSS.
4) BIND Your Solution File To VSS, Do Not Add It
The final step in properly organizing your solution and project files in VSS, to actually place your solution file in VSS. To do this, however, do not click the "Add Solution To Source Control..." menu item. This item, while quick and convenient, usually results in your solution file being created in a folder with a ".root" extension on it, and usually one folder below the folder that you actually specify.
Instead, use the "Change Source Control" menu item. You will receive a pop-up window that displays the current VSS bindings for your projects. You will also see your solution file at the bottom of the list, with "" listed in the "Server Name" column. Click on the solution name, then click the "Bind" button at the top of the pop-up window. If required, log into your VSS database with your username and password. You will now see a pop-up window that lists all of the folders in your VSS database. Traverse the folder structure until you locate the root folder that you created for your solution in step 3. Ensure that this root folder is selected, and click the "OK" button.
You should now see your solution listed at the top of the "Change Source Control" pop-up window, with red wavy lines under the data in the "Server Name" and "Server Binding" columns. This essentially means that VS.NET believes you are trying to bind your solution file to a location in VSS, that is incorrect. Technically, this is correct - however, this is exactly what we want at this point, since the solution file does not exist in VSS yet. Click the "OK" button and you will recieve a large confirmation dialog telling you that "Some projects have been bound to server locations that may be incorrect.". When you receive this message, click the "Continue with these server bindings" button. You will then receive an additional dialog box stating that you may need to check in some files to the server. Click "OK" and let VS.NET do it's magic.
Finally: You should now see all of your projects with the wonderful little lock icon, signifying that they are locked by source control. Your solution, however, should have a red checkmark next to it, signifying that it is currently checked out. Right click on the solution file, and select "Check In" (or use any method of checking in the solution file that you wish). This step is critical - you must check in the solution file at this time, or you risk not having your solution file in VSS at all.
Once you have checked in the solution file, your solution in VSS will be properly organized.
-----------------------------------------------
I hope you find this information useful. I know it is a great help to myself, with the many different solutions that I work with on a daily basis. My knowledge of creating solutions and adding them to VSS in this manner has made me the default "goto guy" for new solutions in my office.
If you have any comments, corrections, etc., please feel free to contact me or register on my website by clicking the "Login" button and registering for a free account. You'll be able to post comments in the weblog entries, as well as post messages in the forums.
Also stay tuned for my post in the "VS.NET and VSS" series: Renaming an item.