Introduction
Many persons and teams use Visual SourceSafe (VSS) together with Visual C++. Visual SourceSafe is easy to use, but it is far from convenient. Many third-party products provide some kind of automatic features to VSS. If you want to do your own automatic tasks, such as auto-build, auto-backup, auto-notification, the tree structure of projects and other information are needed. VSSXML uses VSS Automation interface to dump out the projects information in a VSS database.
I just read the documents and put the code together. But it is good to provide a full example of VSS automation instead of only pieces of code.
Background
Some third-party products that do some automatic tasks with VSS use the add-in mode. That's to say, an add-in DLL is loaded by VSS and be notified when some events occur. Other products use a timer based query mode, they query the VSS database at specific time intervals to see if there are any changes.
VSSXML queries the VSS database and outputs the version information of the project as well as its subitems in XML format, which can be used in other tasks. And, you may modify the source code to do some tasks such as auto-download.
The following products also use VSS automation interface:
Usage
VSSXML is a console program rather than a GUI tool. It provides a few arguments to tell the program which project to dump.
The parameter --database
contains the full path filename of the initialization file of the VSS database. If the path or file name contains any space, a pair of quotation marks(") may be used.
The parameter --item
contains the full path of the item you are interested in, if it is omitted, the root "$/" is used as default.
The parameter --output
contains the output XML filename, if it is omitted, the XML file will be dumped to standard output device stdout
.
The parameters --user
and --password
are needed when the VSS database needs a login to connect to the database. The default user is guest
and the default password is blank.
You may use the format argument=value
or argument value
for each parameter that needs a value.
See the following examples:
Using the code
The main code is short and straightforward. There are no classes, only three functions to dump the VSS database and several functions that deal with the command arguments. Function DumpProject
opens a given project in a VSS database and calls DumpItem
to dump all the projects and files in a recursive way. Function DumpVersion
dumps all the versions of a special file. Only the versions of files are dumped in XML format. The versions of a project contains all the information of its subitems.
You may see the Reference and Further Reading section to get background information about IVSSDatabase
, IVSSItems
, IVSSItem
, IVSSVersions
, IVSSVersion
and other VSS interfaces.
Only a few lines of source are not straightforward like other parts of the program. The following code uses the _NewEnum
and Next
methods of IVSSVersions
to find all the subitems of IVSSVersions
, see the Points of Interest section for details.
IVSSVersions* pVersions = NULL;
pItem->get_Versions(0, &pVersions);
IUnknown* pEnumerator = NULL;
pVersions->_NewEnum(&pEnumerator);
if (pEnumerator)
{
IEnumVARIANT* pVariant = NULL;
pEnumerator->QueryInterface(IID_IEnumVARIANT, (void **) &pVariant);
pEnumerator->Release();
HRESULT h = pVariant->Next((unsigned long) 1, &v, &actual);
while (h==0)
{
IVSSVersion* pVersion = NULL;
v.pdispVal->QueryInterface(IID_IVSSVersion, (void **) &pVersion);
DumpVersion(file, indent+2, pVersion);
h = pVariant->Next((unsigned long) 1, &v, &actual);
}
}
Points of Interest
The most interesting thing about VSS automation is from Microsoft's document, saying that, "The Count
property and Item
method are not implemented in this collection (IVSSVersions
). The only way to use this collection is to call the _NewEnum
method (C++), or use a for each
loop (VB)." The Count
and Item
are implemented in other VSS interfaces.
Because of this, if only the type library ssapi.dll is imported, it is hard to visit the subitems of class IVSSVersions
. File ssauto.h (from Microsoft) contains the declaration of the VSS interfaces.
Need Your Advice
I am now thinking about writing a program to automatically download new versions of source file from VSS database and build them using nmake. I am working on a large project with many other programmers and it costs too much time to build a new version. The feather of automatic download and build to see if there are any compile errors, is needed. The programmer who checked in the files that cause the compile errors will be notified using email.
I have not decided that whether to use the .dsp or .mak files of the project from VSS or create a .mak file by the program. In the first approach, we need the programmers update the .dsp or .mak files immediately after they add or delete files from project. In the second approach, we may encounter problems in creating the .mak files.
Known issues
The program is only intended to be used with Microsoft Visual SourceSafe 6.0. It is tested on Windows 2000. The program does not handle OLE errors, the VSS client should be properly installed.
It seems that the program is a little slower than VSS' client, Visual SourceSafe Explorer.
I do not know how to figure out the users of the database.
Reference and Further Reading
This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.