When a Visual Studio solution or project is placed under source control using the IDE, the IDE receives two key pieces of information from the source control plug-in in the form of strings. These strings, "AuxPath" and "ProjName", are opaque to the IDE, but they are used by the plug-in to locate the solution or project in version control. The IDE typically obtains these strings the first time by calling the SccGetProjPath Function, and it then saves them in the solution or project file for future calls to the SccOpenProject Function. When embedded in the solution and project files, the "AuxPath" and "ProjName" strings are not automatically updated when a user branches, forks, or copies solution and project files that are in version control. To make sure that the solution and project files point to their correct location in version control, users must manually update the strings. Because the strings are meant to be opaque, it may not always be clear how they should be updated.
The source control plug-in can avoid this problem by storing the "AuxPath" and "ProjName" strings in a special file called the MSSCCPRJ.SCC file. It is a local, client-side file that is owned and maintained by the plug-in. This file is never placed under source control but is generated by the plug-in for every directory that contains source-controlled files. To determine which files are Visual Studio solution and project files, a source control plug-in can compare the file extensions against a standard or user-supplied list. Once the IDE detects that a plug-in supports the MSSCCPRJ.SCC file, it ceases to embed the "AuxPath" and "ProjName" strings into solution and project files, and it reads those strings from the MSSCCPRJ.SCC file instead.
A source control plug-in that supports the MSSCCPRJ.SCC file must adhere to the following guidelines:
There can only be one MSSCCPRJ.SCC file per directory.
An MSSCCPRJ.SCC file can contain the "AuxPath" and "ProjName" for multiple files that are under source control within a given directory.
The "AuxPath" string must not have quotes inside it. It is allowed to have quotes around it as delimiters (for example, a pair of double quotes can be used to indicate an empty string). The IDE will strip all quotes from the "AuxPath" string when it is read from the MSSCCPRJ.SCC file.
The "ProjName" string in the MSSCCPRJ.SCC file must match exactly the string returned from the SccGetProjPath function. If the string returned by the function has quotes around it, the string in the MSSCCPRJ.SCC file must have quotes around it, and vice versa.
An MSSCCPRJ.SCC file is created or updated whenever a file is placed under source control.
If an MSSCCPRJ.SCC file gets deleted, a provider should regenerate it the next time it performs a source control operation concerning that directory.
An MSSCCPRJ.SCC file must strictly follow the defined format.
Following is a sample of the MSSCCPRJ.SCC file format (the line numbers are only provided as a guide, and should not be included in the file body):
[Line 1] SCC = This is a Source Code Control file
[Line 3] [TestApp.sln]
[Line 4] SCC_Aux_Path = "\\server\vss\"
[Line 5] SCC_Project_Name = "$/TestApp"
[Line 7] [TestApp.csproj]
[Line 8] SCC_Aux_Path = "\\server\vss\"
[Line 9] SCC_Project_Name = "$/TestApp"
The first line states the purpose of the file and serves as the signature for all files of this type. This line should appear exactly like this in all MSSCCPRJ.SCC files:
SCC = This is a Source Code Control file
What follows is a section of settings for each file, marked by the file name in square brackets. This section is repeated for each file being tracked. This line is a sample of a file name, namely, [TestApp.csproj]. The IDE expects the following two lines. It does not, however, define the style of the values defined. The variables are SCC_Aux_Path and SCC_Project_Name.
SCC_Aux_Path = "\\server\vss\"
SCC_Project_Name = "$/TestApp"
There is no end delimiter to this section. The name of the file, as well as all literals that appear in the file, are defined in the scc.h header file. For more information, see Strings Used as Keys for Finding a Source Control Plug-in.