Sorgular kullanarak programatik olarak iş öğelerini getirme

2025-05-06

Azure DevOps Services

Azure DevOps Services'ta iş öğelerini sorgular kullanarak getirmek yaygın bir senaryodur. Bu makalede, REST API'lerini veya .NET istemci kitaplıklarını kullanarak program aracılığıyla bu senaryoya nasıl uygulanacakları açıklanmaktadır.

Önkoşullar

Kategori	Gereksinimler
Azure DevOps	- Kuruluş.<\br>- Kişisel Erişim Jetonu (PAT).
Geliştirme ortamı	C# geliştirme ortamı. Visual Studio'yu kullanabilirsiniz.

Önemli

Bu makalede örnek olarak Kişisel Erişim Belirteçleri 'ni (PAT) kullanırız, ancak BUR'ları kullanmanızı önermiyoruz. Daha güvenli kimlik doğrulama mekanizmaları için bkz. kimlik doğrulaması kılavuzu.

Visual Studio'da C# projesi oluşturma

Visual Studio'da C# programlama hakkında bilgi için Visual Studio C# programlama belgelerine bakın.

C# kod içeriği

Kod parçacığında aşağıdaki görevler gerçekleşir:

Kimlik Doğrulaması
1. Kişisel Erişim Belirtecinizi (PAT) kullanarak kimlik bilgileri oluşturun.
2. Kimlik bilgilerini kullanarak istemciyi oluşturun.
İş öğelerini alın
1. Kullanmak istediğiniz sorguyu oluşturun.
2. Bu sorgunun sonuçlarını alın.
3. İş öğelerinin her birini ID'lerine göre getirin.

C# kod parçacığı

// nuget:Microsoft.TeamFoundationServer.Client
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

public class QueryExecutor
{
    private readonly Uri uri;
    private readonly string personalAccessToken;

    /// <summary>
    /// Initializes a new instance of the <see cref="QueryExecutor" /> class.
    /// </summary>
    /// <param name="orgName">
    /// An organization in Azure DevOps Services. If you don't have one, you can create one for free:
    /// <see href="https://go.microsoft.com/fwlink/?LinkId=307137" />.
    /// </param>
    /// <param name="personalAccessToken">
    /// A Personal Access Token, find out how to create one:
    /// <see href="/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops" />.
    /// </param>
    public QueryExecutor(string orgName, string personalAccessToken)
    {
        this.uri = new Uri("https://dev.azure.com/" + orgName);
        this.personalAccessToken = personalAccessToken;
    }

    /// <summary>
    /// Execute a WIQL (Work Item Query Language) query to return a list of open bugs.
    /// </summary>
    /// <param name="project">The name of your project within your organization.</param>
    /// <returns>A list of <see cref="WorkItem"/> objects representing all the open bugs.</returns>
    public async Task<IList<WorkItem>> QueryOpenBugs(string project)
    {
        var credentials = new VssBasicCredential(string.Empty, this.personalAccessToken);
        var wiql = new Wiql()
        {
            Query = "Select [Id] " +
                    "From WorkItems " +
                    "Where [Work Item Type] = 'Bug' " +
                    "And [System.TeamProject] = '" + project + "' " +
                    "And [System.State] <> 'Closed' " +
                    "Order By [State] Asc, [Changed Date] Desc",
        };

        using (var httpClient = new WorkItemTrackingHttpClient(this.uri, new VssCredentials(credentials)))
        {
            try
            {
                var result = await httpClient.QueryByWiqlAsync(wiql).ConfigureAwait(false);
                var ids = result.WorkItems.Select(item => item.Id).ToArray();

                if (ids.Length == 0)
                {
                    return Array.Empty<WorkItem>();
                }

                var fields = new[] { "System.Id", "System.Title", "System.State" };
                return await httpClient.GetWorkItemsAsync(ids, fields, result.AsOf).ConfigureAwait(false);
            }
            catch (Exception ex)
            {
                Console.WriteLine("Error querying work items: " + ex.Message);
                return Array.Empty<WorkItem>();
            }
        }
    }

    /// <summary>
    /// Execute a WIQL (Work Item Query Language) query to print a list of open bugs.
    /// </summary>
    /// <param name="project">The name of your project within your organization.</param>
    /// <returns>An async task.</returns>
    public async Task PrintOpenBugsAsync(string project)
    {
        var workItems = await this.QueryOpenBugs(project).ConfigureAwait(false);
        Console.WriteLine("Query Results: {0} items found", workItems.Count);

        foreach (var workItem in workItems)
        {
            Console.WriteLine(
                "{0}\t{1}\t{2}",
                workItem.Id,
                workItem.Fields["System.Title"],
                workItem.Fields["System.State"]);
        }
    }
}

Sorun giderme

Azure DevOps ile program aracılığıyla çalışırken sorgu yürütme, parametre kullanımı veya yöntem aşırı yüklemeleriyle ilgili sorunlarla karşılaşabilirsiniz. Bu bölümde yaygın sorunlar, bunların nedenleri ve bunların etkili bir şekilde nasıl çözümlendikleri hakkında rehberlik sağlanır. Bu sorun giderme adımlarını anlayarak daha sorunsuz tümleştirme sağlayabilir ve çalışma zamanı hatalarını önleyebilirsiniz.

Yaygın sorunlar

Wiql
İsteğe bağlı parametrelerin yanlış kullanımı: özellikle null olan isteğe bağlı parametrelerin doğru şekilde geçirildiğini doğrulayın.
Geçersiz sorgu söz dizimi: Nesnedeki sorgunun Wiql geçerli olduğundan ve beklenen biçimle eşleştiğinden emin olun.

RuntimeBinderException

Azure DevOps'ta QueryByWiqlAsync yöntemiyle çalışırken bir RuntimeBinderException ile karşılaşabilirsiniz. Bu istisna, genellikle metoda geçirilen bağımsız değişkenler, metodun herhangi bir aşırı yüklemesine uymadığında oluşur. Yöntemin imzasını anlamak ve doğru parametre kullanımını sağlamak bu sorunu çözmeye yardımcı olabilir.

Hata:
RuntimeBinderException: Bu özel durum, yönteme geçirilen bağımsız değişkenler yöntemin QueryByWiqlAsync aşırı yüklemelerinden hiçbirine uymadığında oluşur.

Çözüm:
yöntemine geçirilen parametrelerin doğru türlerde ve doğru sırada olduğundan emin olun. Yöntem imzası aşağıdaki gibidir:

public virtual Task<WorkItemQueryResult> QueryByWiqlAsync(
    Wiql wiql,
    bool? continueOnError = null,
    int? top = null,
    object userState = null,
    CancellationToken cancellationToken = default(CancellationToken));

Doğru kullanımı olan örnek kod

Aşağıdaki kod parçacığı, parametrelerin düzgün şekilde tanımlandığından emin olarak yöntemin doğru kullanımını QueryByWiqlAsync gösterir:

using Microsoft.TeamFoundation.WorkItemTracking.WebApi;
using Microsoft.TeamFoundation.WorkItemTracking.WebApi.Models;
using System;
using System.Threading.Tasks;
public async Task QueryWorkItemsAsync(WorkItemTrackingHttpClient client)
{
    var wiql = new Wiql()
    {
        Query = "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = 'YourProjectName'"
    };

    try
    {
        var result = await client.QueryByWiqlAsync(wiql);
        foreach (var workItem in result.WorkItems)
        {
            Console.WriteLine($"Work Item ID: {workItem.Id}");
        }
    }
    catch (Microsoft.CSharp.RuntimeBinder.RuntimeBinderException ex)
    {
        Console.WriteLine($"Error: {ex.Message}");
    }
}

Kodun açıklaması

Wiql nesnesi oluştur: Wiql nesnesi, iş öğelerini getirmek için bir sorgu içerir.
Çağrı Yapın QueryByWiqlAsync: Wiql nesnesini yönteme geçirin.
Özel durumları işleme: Hata ayıklama için hata iletisini yakalayın RuntimeBinderException ve günlüğe alın.

Bu yaklaşımı izleyerek, QueryByWiqlAsync yöntemini düzgün bir şekilde kullanabilir ve RuntimeBinderException gibi yaygın sorunlardan kaçınabilirsiniz.

Aracılığıyla paylaş