Jezda.Common.Integrations.AzureDevOps 3.0.0

Jezda.Common.Integrations.AzureDevOps

A strongly-typed .NET client for Azure DevOps REST API, built on top of Jezda.Common.Integrations. This library simplifies interaction with Azure DevOps by providing easy-to-use methods for Work Items and WIQL queries.

✨ Features

• Work Item Management: Create and retrieve work items.
• WIQL Support: Execute raw WIQL queries and get typed results.
• Project Management: List all projects in the organization.
• Dependency Injection: Ready-to-use IServiceCollection extension.

📦 Installation

Add the project reference or NuGet package:

dotnet add package Jezda.Common.Integrations.AzureDevOps

⚙️ Configuration

Add the following section to your appsettings.json:

{
  "Integrations": {
    "AzureDevOps": {
      "BaseUrl": "https://dev.azure.com/your-organization/",
      "PersonalAccessToken": "your-pat-token",
      "ApiVersion": "7.1"
    }
  }
}

🚀 Usage

1. Register Services

In your Program.cs:

using Jezda.Common.Integrations.Extensions;

builder.Services.AddAzureDevOpsIntegration(builder.Configuration);

2. Inject and Use

Inject IAzureDevOpsClient into your service:

public class MyService
{
    private readonly IAzureDevOpsClient _adoClient;

    public MyService(IAzureDevOpsClient adoClient)
    {
        _adoClient = adoClient;
    }

    public async Task SyncDataAsync()
    {
        // 1. Get all projects
        var projects = await _adoClient.GetProjectsAsync();

        // 2. Get work items via WIQL
        var workItems = await _adoClient.GetWorkItemsByQueryAsync(
            "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'");
    }
}

GetWorkItemsByQueryAsync takes flat queries only. A link query (FROM WorkItemLinks) throws NotSupportedException. The result can hold fewer items than the query matched: an item deleted or made unreadable after the query ran is left out, with a warning in the log that names the organisation and the missing ids. A batch answered without a list throws instead, because it says nothing about the items in it.

🔐 Errors and authentication

Both IAzureDevOpsClient and the IExternalTaskProvider for Azure DevOps report failures as HttpRequestException with StatusCode set, so a caller can tell a rejected token from anything else:

ValidateConnectionAsync returns a rejection only for a rejected token. Every other failure propagates, so an outage is not shown to the user as a bad PAT.

The work item check runs only once projects passed, with the same token from the same address, so any refusal there is the missing "Work Items (Read)" scope, not a bad token, Conditional Access or an address block. For a sign-in page, Detail names the redirect target (host and path), which tells Azure DevOps from a gateway with its own /_signin.

A 403 on _apis/projects is not always about the token: Conditional Access, an IP allow-list or a WAF can answer it for a valid PAT. Validation still returns a rejection, AccessDenied, and logs a warning with the start of the response body, which tells these apart.

Validation sends two requests: _apis/projects, which needs "Project and Team (Read)", and _apis/wit/fields, which needs "Work Items (Read)". A PAT missing either scope returns a rejection, instead of validating and failing later on the first work item call.

Keeping redirects off

AddAzureDevOpsIntegration turns off redirects on the default primary handler. Without that, a redirect drops Authorization and a valid PAT reads as expired. It also sets the X-TFS-FedAuthRedirect: Suppress header, which asks for 401 instead of a redirect to sign-in. Four setups need care:

• A custom primary handler registered before AddAzureDevOpsIntegration: one that is not SocketsHttpHandler or HttpClientHandler stays as it is, and a warning is logged. Make sure it does not follow redirects.
• ConfigurePrimaryHttpMessageHandler called after AddAzureDevOpsIntegration: the handler replaces the configured one and nothing warns, so set AllowAutoRedirect = false on it yourself.
• AzureDevOpsClient given an HttpClient made outside DI: set AllowAutoRedirect = false on its handler, and send the header yourself.
• AzureDevOpsTaskProvider built on your own IHttpClientFactory: the same two apply to the client it creates under AzureDevOpsTaskProvider.HttpClientName.

🛠️ Key Models

• AdoWorkItem: Represents a simplified work item with generic Fields dictionary. Url is the REST resource, which answers JSON; HtmlUrl is the page a person opens (_links.html.href, asked for with $expand=links), null when the answer had no links.
• AdoProject: Contains project details (Id, Name, Description, Url).