Building a simple Vault Client.
There are lots of Vault users out there. Most are content to just use it to check in changes to their files and occasionally get an old version. Then there are others who want to get the most out of Vault. In this series, I'm going to try to help out power users by showing them how to write simple programs that connect to Vault and extract some interesting bits of information. Here's a list of some of the samples I want to guide you through
1. A small program to parse the log file from a failed build, which connects to Vault to determine the last user who changed the line that caused the build failure.
2. A small program to generate a changelog to track the differences between builds.
3. A Vault client built in VB to display the Vault tree and track who's making changes.
4. A simple plugin that will start a build after every change to the tree.
I have more ideas, and would love to get feedback from the power users out there who have ideas.
The template
This all starts with a template project that can connect to Vault. In the rest of this post, I'll walk you through a simple template. I'll just be addressing the most interesting bits here, but you can download the full solution here. This is assuming that you've already downloaded and installed the Vault ClientAPI.
ClientInstance myClient = new ClientInstance();
This line creates a new ClientInstance, which is the highest level object you can use to talk to the Vault server. The client instance holds the connection, tree cache, working folder data, pretty much everything. If there's something that you want to do, you probably want to go through client instance to do it.
myClient.Init(VaultClientNetLib.VaultConnection.AccessLevelType.Client);
myClient.Login(hostname, username, password);
These two lines log you on to the Vault server. To understand what these two functions do, it's best to think of them in terms of how the Vault GUI client works. Init is called before the login dialog comes up, to set up the web service object. Login is called after you hit ok on the login dialog. Note that Init is where you declare if you are an admin client or a regular client. Certain methods are only available to admin clients.
VaultRepositoryInfo[] reps = null;
//List all the repositories on the server.
client.ListRepositories(ref reps);
//Search for the one that we want.
foreach (VaultRepositoryInfo r in reps)
{
if (String.Compare(r.RepName,repositoryName, true) == 0)
{
//This will load up the client side cache files and refresh the repository structure.
//See http://support.sourcegear.com/viewtopic.php?t=6 for more on client side cache files.
client.SetActiveRepositoryID(r.RepID, client.Connection.Username, r.UniqueRepID, true, true);
break;
}
}
This loop is necessary due to a deficiency the Vault API. We never got around to implementing a nice function to connect to a repository based on the repository name. This means that (until we fix it) every program that uses the Client API will need to jump through this particular hoop. To explain what is going on, the client is requesting a list of all of the repositories on the Vault server, then looping through them to find the one that we want. When we find it, we use the clientInstance's SetActiveRepositoryID to load it. SetActiveRepositoryID does a lot. It loads the client side cache files and refreshes all the repository information from the server.
Once you've jumped through the four necessary hoops, you're finally connected and ready to do something. To recap, the hoops are:
1. Construct ClientInstance
2. Init
3. Login
4. SetActiveRepositoryID
The next post will actually do something with your Vault connection.