Walkthru:The Version Control Object Model 

Glossary Item Box

Working with the Version Control Object Model

Team Foundation Source Control

One of the key benefits of Visual Studio Team System is that in addition to providing world-class source control through Team Foundation Source Control, VSTS also allows programmatic access to the repository through the Version Control Object Model. Programmatic access through this object model allows customers and partners to automate certain interactions if desired, and also allows partners to seamlessly integrate their components with source control. The object model also makes it possible to create custom policy constraints that can be enlisted to validate developer checkins.

The Version Control Object Model

The Version Control Object Model does a very good job of shielding developers from the underlying complexity involved in programmatically interacting with a local client, upon which a workspace is created, and a potentially remote server (the Team Foundation Server). A key benefit of the object model is that it encapsulates, or hides, all of the remoting and marshalling issues, and enables development through a simple set of objects that abstract the underlying interactivity taking place between the source control client and server. The TeamFoundationServer object represents an instance of a Team Foundation Server, and the SourceControl object, which is a member of the TeamFoundationServer object, exposes another key abstraction: the WorkSpace object. The workspace object, in turn, exposes valuable properties and methods that manage changesets, pending changes, and Check In interaction.

Walkthrough – working with the version control object model

The best way to show the simplicity of the Version Control Object Model is to take it for a test drive. The following demonstration will show you how to create a console application that will provide a cursory overview of some of the key components of programmatically interacting with the Version Control Object Model.

1.  In Visual Studio, select the File | New | Project menu option. Create a new C# Console Application, specifying "VCObjectModel" as the Name. Then click OK.

2.  In Solution Explorer , right click on the References node and select the Add Reference menu option. From the Add Reference dialog, select the Browse tab, and then navigate to Program Files\Microsoft Visual Studio 8\Common7\IDE\PrivateAssemblies\.

Once there, select the following three assemblies (.dlls) to add to your project (hold down the CTRL key to select multiple files):

Microsoft.TeamFoundation.Client
Microsoft.TeamFoundation.VersionControl.Client
Microsoft.TeamFoundation.VersionControl.Common

Once you have selected all three of the above files, click the OK button to add them to your project.

3.  At the top of Program.cs, add the following using directives:

  using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.VersionControl.Common;
using Microsoft.TeamFoundation.VersionControl.Client;
using System.IO;

With these references in place, you are now ready to programmatically interact with the Version Control Object Model. Interacting with the Object Model is a fairly straight-forward process involving the process of creating a connection to the relevant server objects (TFS, and then the Version Control Service), mapping a workspace, getting files, and then notifying the appropriate objects of Added or Edited Files.

4.  Replace the Main() method in Program.cs with the following code (which will serve as the framework for subsequent steps):

  static void Main(string[] args)
{
    // Patterned after BasicSccSample from VSTS Section
    //  of VS SDK (in the Version Control folder)
    Workspace workspace = null;
    try
    {
        // Connect to TFS Source Control
        
        // Create a Workspace
        
        // Get Files

        // Create a New Directory/File
        
        // Append Files
        
    }
    catch (Exception ex)
    {
        Console.WriteLine("Exception Encountered: ");
        Console.Write(ex.Message + "\n");
    }
    finally
    {
        // clean up the workspace for subsequent passes.
        if (workspace != null)
            workspace.Delete(); 
    }
    Console.WriteLine("Press any key to continue");
    Console.ReadLine();
}

Note that a Workspace instance is declared outside of the try/catch block, and checked in the finally block to see if it needs to be deleted. This was done with the expectation that once you've completed the walkthrough that you may want to add some of your own code and experimentation to this sample. If you do so, just make sure to keep the finally block intact or you will run into collisions if you attempt to create a Workspace mapping that is already registered with the TFS.

5.  Add code to create a connection to the TFS and to the VersionControlServer by pasting the following code just below the // Connect to TFS Source Control comment in Main() :

Console.WriteLine("Please Enter the Name of your TFS Server");
string tfsName = Console.ReadLine();

TeamFoundationServer tfs =
    TeamFoundationServerFactory.GetServer(tfsName);
VersionControlServer vcs =
    (VersionControlServer)tfs.GetService(typeof(VersionControlServer));

6.  Now specify the repository and workspace mapping by adding the following code just below the // Create a Workspace comment:

  string repository = "$/"; // root

// location to check out files to:
string workspacePath = @"c:\workspace";

workspace = vcs.CreateWorkspace("TestWorkSpace", vcs.AuthenticatedUser);
WorkingFolder folder = new WorkingFolder(repository, workspacePath);

This code maps a repository (in this case, the root (or all repositories) currently held in the Version Control Server to a location on the local, or client, machine. If you wanted, you could easily modify the values for the repository or workspacePath variables – or provide a way to make them interactive, etc.

7.  Paste the following code below the // Get Files comment to create a local copy of the files by specifying a workspace mapping:

workspace.CreateMapping(folder);
Console.WriteLine("Getting Files.");
workspace.Get();
Console.WriteLine("Done Getting Files");

8.  Add some very simple code to create a new directory and file by pasting the following code below the // Create a New Directory/File comment:

  string newDir = 
    Path.Combine(workspace.Folders[0].LocalItem, "test");
Directory.CreateDirectory(newDir);
Console.WriteLine("Enter the name of a file to create e.g. test.cs");
string fileName = Console.ReadLine();
string filePath = Path.Combine(newDir, fileName);
using (StreamWriter sw = new StreamWriter(filePath))
    sw.WriteLine("Newly Added Text");
Console.WriteLine("New Directory and File Added.");

9.  Add some very simple code to create a new directory and file by pasting the following code below the // Append Files comment:

workspace.PendAdd(newDir, true);
PendingChange[] changes = workspace.GetPendingChanges();

if (changes.Length > 0)
{
    int changeSetNumber = 
        workspace.CheckIn(changes, "User Comment Here");
    Console.WriteLine("checkIn: {0}", 
        changeSetNumber.ToString());
}
else
    Console.WriteLine("No Changes Detected. (Filename likely not new/added.)");

// See VSTS documentation in VS SDK for more examples/functionality.

The Workspace class provides a handful of PendX() methods, where X represents useful functionality on the order of Add, Edit, Delete, Rename, etc. The purpose of these methods are to ‘bundle' changes into VSTS ChangeSet constructs which can be evaluated as needed, and then marshaled to the Version Control Server through the CheckIn() method.

10.  Compile and test your code by pressing F5.

11.  As you proceed through the application you will be initially prompted to specify the name of you TFS instance. You'll then be prompted to specify a name for a file to be added to the current repository.

The Version Control Object Model makes interaction with Team Foundation Server completely accessible via programmatic means. This means that customers and partners are free to leverage it augment their own Extensions to Visual Studio (i.e. such as new Project and File Types – or editor resources), create their own "Continuous Integration" solutions, or use it in other ways that they see fit. The VSTS Section of the VS SDK provides a number of targeted resources and additional resources including samples and documentation designed to showcase the various ways in which the Object Model can be successfully used to help extend Visual Studio.