VSSXML: dump Visual SourceSafe project in XML format

• Download source files - 12.4 Kb
• Download demo project - 7.99 Kb

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:

• Visual SourceVizor 2.0
• VssMon 1.0

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:

• vssxml --database="C:\Program Files\Microsoft Visual Studio\Common\VSS\srcsafe.ini" --output c:\temp\test.xml --item="$/My Project/VSSXML"

  This command dumps the branch $/My Project/VSSXML of local VSS database to local file c:\temp\test.xml.

• vssxml --database="C:\Program Files\Microsoft Visual Studio\Common\VSS\srcsafe.ini" --output c:\temp\test.xml --item="$/My Project/VSSXML" --user=admin --password mypass

  This command dumps the same branch using login - admin and password - "mypass".

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

• Documents in MSDN:
  1. Tim Winter. Visual SourceSafe 6.0 Automation. September 1998.

     Describes the VSS object model and VSS events. Good for beginners.

  2. Ken Felder. Microsoft Visual SourceSafe OLE Automation. October 1995.

     Describes the basic model in VB.

• HOWTOs in MSDN:
  1. HOWTO: Get History Using SourceSafe OLE Automation in C++.

     Describes how to use _NewEnum and Next to get versions.

  2. HOWTO: Write Automation for Visual SourceSafe 5.0/6.0.

     Describes how to judge the version of VSS used.

  3. HOWTO: Open a SourceSafe Database with OLE Automation in C++.

     Describes how to open a VSS database.