Edit

Share via

Migrate from WIT Client OM to REST APIs

Azure DevOps Services

Important

Legacy technology replacement required

The WIT Client OM (Work Item Tracking Client Object Model) is legacy technology that should be replaced with modern REST-based .NET client libraries. Migration provides better performance, security, and cross-platform support.

This guide helps you migrate your .NET code from the deprecated WIT Client OM to modern REST APIs. The migration offers significant benefits:

✅ Modern advantages:

  • Asynchronous operations for better performance
  • Modern authentication with managed identities and service principals
  • Cross-platform support (.NET Core, .NET 5+, and .NET Framework)
  • Active development and ongoing support

❌ Legacy limitations:

  • Limited to .NET Framework and Windows only
  • Synchronous, blocking operations
  • Outdated authentication methods

Migration overview

Step 1: Update NuGet packages - Replace WIT Client OM with modern REST client packages Step 2: Update authentication - Migrate to secure, modern authentication methods Step 3: Convert operations - Replace synchronous calls with asynchronous REST operations

For detailed code examples and step-by-step migration samples, see the GitHub Azure DevOps WIT Client OM Migration Guide.

Common scenarios migration table

The following table shows how to migrate common work item operations from legacy WIT Client OM to modern REST APIs:

Scenario Legacy WIT Client OM Modern REST API
Get list of work items WorkItemStore.Query Work Items - List
Get single work item WorkItemStore.GetWorkItem Work Items - Get Work Item
Create new work item WorkItem Work Items - Create
Update existing work item WorkItem.Fields Work Items - Update
Validate a work item WorkItem.IsValid(),
WorkItem.Validate()		 Work Items - Update (validate only)
Create a link to an existing work item WorkItem.WorkItemLinks.Add Work Items - Update (add link)
Add a comment WorkItem.History Work Items - Update (add comment)
Create a hyperlink WorkItem.Links.Add() Work Items - Update (add hyperlink)
Add an attachment WorkItem.Attachments.Add() Work Items - Update (add attachment)
Query work items using WIQL WorkItemStore.Query() Wiql - Query by Wiql
Run an existing query to get work items WorkItemStore.Query() Wiql - Query by ID
Get list of work item types for project Category.WorkItemTypes Work Item Types - List
Get work item type details Category.WorkItemTypes Work Item Types - Get
Get list of fields for a work item type WorkItemType.FieldDefinitions Work Item Types Field - List
Get field details WorkItemType.FieldDefinitions Work Item Types Field - Get

Authentication migration

Legacy authentication (❌ Replace):

// WIT Client OM with basic authentication
using (var tpc = new TfsTeamProjectCollection(new Uri(collectionUri)))
{
    tpc.Authenticate();
    var workItemStore = tpc.GetService<WorkItemStore>();
}

Modern authentication (✅ Recommended):

// REST client with managed identity (for Azure-hosted apps)
var credentials = new VssAzureIdentityCredential();
using var connection = new VssConnection(new Uri(collectionUri), credentials);
var witClient = connection.GetClient<WorkItemTrackingHttpClient>();

// Alternative: Service principal for CI/CD
// var credentials = new VssServicePrincipalCredential(clientId, clientSecret, tenantId);

// Alternative: PAT for development/testing
// var credentials = new VssBasicCredential(string.Empty, personalAccessToken);

Next steps and resources

📖 Essential migration resources

🔧 Code examples and tools

🆘 Support and community

🔄 Related migrations

Tip

Start your migration: Begin with authentication guidance to choose the right approach, then see .NET client library samples for working code examples.