Atlassian.NET SDK: JQL Builder and Extensions for ASP.NET Core

This repo hosts extensions to the popular Atlassian.NET SDK. It is licensed with the Apache 2.0 license.

Extensions for ASP.NET Core

NuGet Package: Atlassian.SDK.AspNetCore, supports .NET Core 3.1 and above.

Dependency Injection

This package provides full Dependency Injection support for the services exposed by the underlying Atlassian.NET SDK. Extension methods are used to register Jira in your DI Container, allowing you to consume the services from your Controllers, Razor Pages, scoped services, etc. using standard constructor injection.

Example

using Atlassian.Jira;
using Atlassian.Jira.AspNetCore;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;

namespace MyRadJiraProj
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            // Register a Jira instance in your application’s Startup class
            services.AddJiraWithBasicAuth("JiraBaseUrl", "UserName", "Password");
        }
    }

    public class MyCoolController : ControllerBase
    {
        readonly IIssueService _issueService;

        // Inject the Issue Service in your service’s constructor
        public MyCoolController(IIssueService issueService)
        {
            _issueService = issueService;
        }
    }
}

Common Services

• IIssueService
• IJiraUserService
• IProjectService

Other Jira Services

• IIssueFieldService
• IIssueFilterService
• IIssueLinkService
• IIssuePriorityService
• IIssueRemoteLinkService
• IIssueResolutionService
• IIssueStatusService
• IIssueTypeService
• IJiraGroupService
• IJiraRestClient
• IProjectComponentService
• IProjectVersionService
• IScreenService
• IServerInfoService

IAsyncEnumerable Extensions

This package provides extension methods that return IAsyncEnumerable<T>s where the underlying Atlassian.NET SDK returns Task<IPagedQueryResult<T>>. This greatly simplifies consuming paged Jira REST APIs, as the enumerator handles the paging automatically, and is especially powerful when used with the System.Linq.Async NuGet package. In addition, the IIssueService.GetAsyncQueryable() extension method provides an async alternative to the underlying IIssueService.Queryable LINQ provider. The returned IQueryable will throw an exception if a LINQ method is called that would cause the query to be evaluated synchronously. Instead, call Prepare() to convert the IQueryable to an IAsyncEnumerable.

Method Comparison

Type	“Old” Method	Extension Method
IIssueService	GetIssuesFromJqlAsync()	QueryIssuesAsyncEnum()
IIssueService	GetPagedCommentsAsync()	GetCommentsAsyncEnum()
IIssueService	GetSubTasksAsync()	GetSubTasksAsyncEnum()
IIssueFilterService	GetIssuesFromFavoriteAsync()	GetIssuesAsyncEnum()
IJiraGroupService	GetUsersAsync()	GetUsersAsyncEnum()
IProjectVersionService	GetPagedVersionsAsync()	GetVersionsAsyncEnum()
Issue	GetPagedCommentsAsync()	GetCommentsAsyncEnum()
Issue	GetSubTasksAsync()	GetSubTasksAsyncEnum()
Project	GetPagedVersionsAsync()	GetVersionsAsyncEnum()

JQL Builder

NuGet Package: Atlassian.SDK.JqlBuilder, supports .NET Standard 2.0 and above.

This package provides a fluent API for creating JQL queries of any complexity. The primary class is Atlassian.Jira.JqlBuilder.Jql, which is useful with import static. The Jql class provides nested JqlFields and JqlFunctions classes with well-known JQL Fields and JQL Functions. Call ToString() to return the JQL representation of the built expression.

This package is automatically included with Atlassian.SDK.AspNetCore, but it can be referenced alone for use with .Net Framework projects or non-ASP.NET Core projects.

Examples

// Compare a built-in field
var jql1Expr = Jql.Fields.Assignee == "johnny_appleseed";
// 'assignee' = 'johnny_appleseed'

// Compare to a custom field by name
var jql2Expr = Jql.Field("My Custom Field") > 47;
// 'My Custom Field' > 47

// Compare to a custom field by number
var jql3Expr = Jql.Field(10780).NotIn("foo", "bar");
// cf[10780] NOT IN ('foo', 'bar')

// Use a built-in JQL Function
var jql4Expr = Jql.Fields.IssueKey.In(
    Jql.Functions.UpdatedBy("momotaro", new DateTime(2020, 1, 1), new DateTime(2020, 12, 31)));
// 'issueKey' IN updatedBy('momotaro', '2020/01/01', '2020/12/31')

// Combine two expressions with AND
var jql5Expr = Jql.Fields.Summary.Like("hello") & Jql.Fields.Description.Like("world");
// ('summary' ~ 'hello' AND 'description' ~ 'world')

// Combine multiple expressions
var jql6Expr = Jql.Any(
    Jql.Fields.Assignee == "johnny_appleseed", Jql.Fields.Creator == "momotaro",
    Jql.Fields.Reporter == "johnny_appleseed", Jql.Fields.Watcher  == "momotaro"
);
// ('assignee' = 'johnny_appleseed' OR 'creator' = 'momotaro' \
//  OR 'reporter' = 'johnny_appleseed' OR 'watcher' = 'momotaro')

// Sort the results or a query
var jql7Expr = (Jql.Fields.Project == "TIX").OrderBy(Jql.Fields.Created);
// 'project' = 'TIX' ORDER BY 'created' ASC

Note

This library does not currently support JQL’s WAS or CHANGED operators.