WorkspaceCheckInParameters and ShelvesetCheckInParameters

Many Team Foundation Server customers have developed custom tools and processes that leverage our public client object model in order to automate tasks specific to their organization. With version control, one of the most common tasks to automate is checking in. Since our initial release in 2005, customers have been able to use the Workspace.CheckIn family of methods for this purpose.

In TFS 2010, we’ve added new features related to the process of checking in, but we didn’t want to create more and more overloads of the Workspace.CheckIn method to support them. As a result, in 2010 we’ve added a single new overload that takes a WorkspaceCheckInParameters object.

public int CheckIn(WorkspaceCheckInParameters checkinParameters);

The legacy methods from TFS 2005 and 2008 are still present and fully supported. But you may find that flags and settings related to new features of TFS 2010 (such as gated check-in) are only available through the WorkspaceCheckInParameters overload.

Put simply, the WorkspaceCheckInParameters object encapsulates all the necessary information to complete a check-in from a workspace. Here’s a simple example which checks in all pending changes, with a provided comment.

WorkspaceCheckInParameters wcip = new WorkspaceCheckInParameters(myWorkspace.GetPendingChanges(), “My changeset comment!”);
myWorkspace.CheckIn(wcip);

The above example is equivalent to the following call that uses one of the older CheckIn() overloads. In simple cases like this, we don’t expect that you’ll go to the trouble of using a WorkspaceCheckInParameters object. There’s no advantage to it in this case.

myWorkspace.CheckIn(myWorkspace.GetPendingChanges(), “My changeset comment!”);

An advanced example

The constructors on WorkspaceCheckInParameters are intentionally limited. If we were to go down the road of implementing constructor overloads for every possible combination of flags and parameters, we would have put ourselves back in the same place we started – a nightmare situation of dozens of overloads. Instead, the model we’ve taken is to provide reasonable defaults on the WorkspaceCheckInParameters object. You can then adjust whatever flags and parameters are needed for your scenario before calling Workspace.CheckIn.

Here’s a more complex example which tries to commit a changeset on behalf of another user, and bypasses gated check-in if any of the pending changes being committed are to paths protected by a gated build definition.

WorkspaceCheckInParameters wcip = new WorkspaceCheckInParameters(“My comment!”);
wcip.PendingChanges = myWorkspace.GetPendingChanges();
wcip.Author = “CONTOSO\ClarkKent”;
wcip.OverrideGatedCheckIn = true;
myWorkspace.CheckIn(wcip);

You’ll find that this call will fail if you don’t have permission to override gated check-in, or permission to check in on behalf of another user. (It will also fail if the user CONTOSO\ClarkKent doesn’t exist. J)

Checking in a shelveset directly

One new feature in TFS 2010 is the ability to directly check in a shelveset. In previous releases, customers were required to unshelve the shelveset into a workspace and check in from there. To support this feature we’ve added new methods to the VersionControlServer object.

public int CheckInShelveset(String shelvesetName, String ownerName);
public int CheckInShelveset(ShelvesetCheckInParameters shelvesetCheckInParameters);

There is some intentional parallelism here with the Workspace.CheckIn methods. The first method is likely to be the most commonly used, just as the older, non-WorkspaceCheckInParameters methods are likely to be the most commonly used workspace check-in methods. For advanced scenarios, you can instantiate a ShelvesetCheckInParameters object, adjust the flags, and then call CheckInShelveset.

Here’s an example which checks in a shelveset BugFixes;CONTOSO\ClarkKent and then deletes the shelveset if the check-in successfully completes.

ShelvesetCheckInParameters scip = new ShelvesetCheckInParameters(“BugFixes”, “CONTOSO\ClarkKent”);
scip.DeleteShelveset = true;
myVersionControlServer.CheckInShelveset(scip);

Since the Author property of the ShelvesetCheckInParameters was not specified in this case, the changeset resulting from this check-in will be attributed to the user who called CheckInShelveset, not the owner of the shelveset. Additionally, the requested deletion of the shelveset only occurs if the calling user has CheckinOther permission for the items in the shelveset. (This is so a non-privileged user cannot go around causing others’ shelvesets to disappear.)