WorkItem.PartialOpen Method

  • Article

TFS 2018 | TFS 2017 | TFS 2015

Opens this work item for modification by loading only the latest revision of this WorkItem. Whenever possible, use this method instead of Open because PartialOpen provides better performance.

Namespace: Microsoft.TeamFoundation.WorkItemTracking.Client
Assembly: Microsoft.TeamFoundation.WorkItemTracking.Client (in Microsoft.TeamFoundation.WorkItemTracking.Client.dll)

Syntax

C#

 public void PartialOpen()

C++

 public:
void PartialOpen()

F#

 member PartialOpen : unit -> unit

JScript

 public void PartialOpen()

VB

 'Declaration
Public Sub PartialOpen

Exceptions

Exception Condition
ValidationException This WorkItem instance does not belong to a WorkItemCollection.
DeniedOrNotExistException This WorkItem instance could not be opened for edit correctly.

Remarks

The PartialOpen method loads the field data for only the latest revision of the work item. It does not load non-field data such as links, attachments, and historical revisions. Use this method instead of Open if you only need to work with the latest field data for a work item.

PartialOpen is designed for use within a paging context. When you call PartialOpen on one work item, the entire page of work items will be fetched in a single round-trip to the server. This makes PartialOpen ideal for use in a paging context, such as when displaying and editing pages of work items. If you use Open, it will only fetch one work item in a single round-trip, which is less efficient when working with pages of data.

There are two modes of fetching used by PartialOpen, which the caller can use to determine which fields to fetch. These two modes correspond to whether the DefaultProjectHint is specified or unset in the owning WorkItemCollection object.

(Mode 1) Default - Fetch all the fields of the work item, when project hint is unset.

(Mode 2) Optimized - Fetch only the fields relevant to a particular project, when project hint is specified. This is most optimal and recommended when all workitems are from the same project.

By using PartialOpen, you can save bandwidth, resources, and time by paging in data for multiple work item fields up to the page size that is specified in WorkItemCollection.PageSize. For Azure DevOps Services, the Open method is rate limited whereas PartialOpen is not.

This method does nothing if IsPartialOpen, IsOpen or IsNew are true.

Sample Code

The following code snippet shows how to use PartialOpen to update a list of work items returned from a query.

private static void UpdateWorkItemsUsingPartialOpen()
{

    // create TfsTeamProjectCollection instance using default credentials
    var collectionUri = "https://localhost:8080/tfs/DefaultCollection";
    
    using (TfsTeamProjectCollection tpc = newTfsTeamProjectCollection(newUri(collectionUri)))
    {
        // get the WorkItemStore service
        var workItemStore = tpc.GetService<WorkItemStore>();

        // get the project context for the work item store

        var teamProjectName = "My Favorite Project";

        Project workItemProject = workItemStore.Projects[teamProjectName];

        // search for the 'My Queries' folder

        var queryFolder = workItemProject.QueryHierarchy.FirstOrDefault(qh => qh isQueryFolder && qh.IsPersonal) asQueryFolder;

        if (queryFolder != null)
        {

            // Search for the saved query.
            var queryName = "PartialOpen Sample";
            var newBugsQuery = queryFolder.FirstOrDefault(qi => qi isQueryDefinition && qi.Name.Equals(queryName)) asQueryDefinition;

            if (newBugsQuery == null)
            {
                // If the query does not exist, create it.
                var queryString = string.Format("SELECT [System.Id], [System.WorkItemType], [System.Title], [System.AssignedTo], [System.State], [System.Tags] FROM WorkItems WHERE [System.TeamProject] = '{0}' AND [System.WorkItemType] = 'Bug' AND [System.State] = 'New'", teamProjectName);
                newBugsQuery = newQueryDefinition(queryName, queryString);
                queryFolder.Add(newBugsQuery);
                workItemProject.QueryHierarchy.Save();
            }

            // Run the query.
            WorkItemCollection workItems = workItemStore.Query(newBugsQuery.QueryText);

            // Supply the project hint to only fetch necessary data for the project.
            workItemCollection.DefaultProjectHint = workItemProject.Id;

            var newAssignee = "John Smith";

            foreach (WorkItem workItem in workItems)
            {
                // PartialOpen to fetch fields without underlying lists for entire query page.
                // Using Open() here will fetch too much unnecessary data, and hence is undesirable.
                workItem.PartialOpen();

                // Edit the fields as needed.
                workItem["System.AssignedTo"] = newAssignee;

                // Save your changes.
                workItem.Save();

                // Write work item to console.
                Console.WriteLine("Assigned {0} {1} to {2}", workItem.Id, workItem.Fields["System.Title"].Value, newAssignee);

                // Free memory.
                workItem.Close();
            }
        }
    }
}

.NET Framework Security