How to validate check-in policies, evaluate check-in notes, and check for conflicts

Buck Hodges

In the version control API, the CheckIn() method does not evaluate check-in policies and validate check-in notes.  It provides with the ability to supply both an override comment and check-in notes, as applicable, but the evaluation and validation must have been performed prior to calling CheckIn().  The reason for this is that in a real-world application, you will evaluate check-in policies and validate check-in notes at points in time that make sense for whatever you are writing.  For example, the Visual Studio environment will evaluate check-in policies when certain events are triggered.  Also, applications that are converting from a different version control system to TFS will want to bypass these checks.

The EvaluateCheckin() method evaluates policies and validate check-in notes.  It also checks for conflicts.  Here is the method signature along with its documentation.

    //********************************************************************************************
    /// <summary>
    /// Evaluate the changes to see if they are ready for checking in.
    /// </summary>
    /// <param name=”options”>Selects what to check (notes, policies, conflicts).</param>
    /// <param name=”allChanges”>All pending changes for the workspace (needed by checkin policies).
    /// </param>
    /// <param name=”changes”>List of changes to evaluate.</param>
    /// <param name=”comment”>Comment to go along with the checkin.</param>
    /// <param name=”checkinNote”>Any applicable checkin notes data.</param>
    /// <param name=”workItemChanges”>List of work item changes to occur with this checkin (supplied to checkin policies).</param>
    /// <returns>the results of what was checked</returns>
    //********************************************************************************************
    public CheckinEvaluationResult EvaluateCheckin(CheckinEvaluationOptions options,
                                                    PendingChange[] allChanges,
                                                    PendingChange[] changes,
                                                    String comment,
                                                    CheckinNote checkinNote,
                                                    WorkItemCheckinInfo[] workItemChanges)

The options parameter controls what is evaluated and is a simple flag enum.

    //********************************************************************************************
    /// <summary>
    /// Used in pre-checkin evaluation, this enumeration is used to specify which aspects of a
    /// checkin should be evaluated.
    /// </summary>
    //********************************************************************************************
    [Flags]
    public enum CheckinEvaluationOptions
    {
        Notes = 0,
        Policies = 1,
        Conflicts = 2,
        All = -1,
    }

The result of the function is a CheckinEvaluationResult, which has the following properties.

    //********************************************************************************************
    /// <summary>
    /// These are the checkin conflicts returned by the server.
    /// </summary>
    //********************************************************************************************
    public CheckinConflict[] Conflicts

    //********************************************************************************************
    /// <summary>
    /// These are the checkin note problems (missing required notes, invalid checkin notes, etc.).
    /// </summary>
    //********************************************************************************************
    public CheckinNoteFailure[] NoteFailures

    //********************************************************************************************
    /// <summary>
    /// These are the checkin policy failures.
    /// </summary>
    //********************************************************************************************
    public PolicyFailure[] PolicyFailures

    //********************************************************************************************
    /// <summary>
    /// If evaluating policies throws an exception, this is the exception that occurred.  It is null
    /// otherwise.
    /// </summary>
    //********************************************************************************************
    public Exception PolicyEvaluationException

The properties will be set according to the options you specify and according to what fails.  So if you don’t request policy evaluation, for example, or there are no policy failures, the PolicyFailures property will be an empty array.

0 comments

Leave a comment

Feedback usabilla icon