Youtrack logo

The YouTrack Blog

Powerful project management for all your teams
Get YouTrack for free
How-To's Tips & Tricks

YouTrackSharp 3.0 beta – A .NET Standard Client for YouTrack

Maarten Balliauw
Maarten Balliauw

YouTrackSharpPlease welcome a brand new (preview) version of YouTrackSharp – a .NET library to work with the YouTrack REST API. It’s a complete rewrite from the previous version, since a lot of things in the .NET world have changed.

First of all, YouTrackSharp now targets  .NET Standard 1.3, which means it can now be used with pretty much any .NET platform, including .NET Framework 4.6, .NET Core, Mono, Xamarin, and UWP. We wanted to make sure many different applications could be developed with YouTrackSharp, on many platforms.

Another benefit of being on this new stack is we were able to make YouTrackSharp async all the way. And we were able to tackle some other things, too, like handling serialization of YouTrack’s timestamps into DateTime where possible. Let’s have a look!

Getting started

We are distributing YouTrackSharp as a NuGet package, which means it can be easily installed into a project using Visual Studio, Rider, the .NET CLI, Paket or VS Code.

Install-Package YouTrackSharp

Once that is done, we can start working with it. To communicate with a YouTrack server instance, we’ll need a connection. It is recommended to always use permanent tokens to authenticate against YouTrack, using the BearerTokenConnection class. For YouTrack instances that do not have token support, UsernamePasswordConnection can be used.

var connection = new BearerTokenConnection(
    "https://example.myjetbrains.com/youtrack/", "perm:abcdefghijklmn");

Once we have a connection instance, we can start working with various services that are available through extension methods on our connection. For example if we want to dump all issues with their id, summary and current state, we can do so through the IssuesService:
var issuesService = connection.CreateIssuesService();
var issues = await issuesService.GetIssuesInProject("PROJ", take: 250);

foreach (var issue in issues)
{
    Console.WriteLine("{0} {1} - State: {2}",
        issue.Id,
        issue.Summary,
        issue.GetField("State")?.AsString());
}

One thing to note here is that some fields are available as a direct property on the Issue, like Id and Summary, while others are available using the GetField() method. Since not all projects have the same fields, these project-specific fields are available using GetField() and SetField(). An added benefit of using the GetField() method is that it allows returning the value AsString(), AsDateTime(), AsCollection() or AsInt32(). Prefer working with dynamic? That’s fine, too, but keep in mind you’ll have to cast the correct types manually then.
var dynamicIssue = issue.AsDynamic();

Console.Write("Issue type for {0} is: {1}",
    dynamicIssue.Id, dynamicIssue.Type[0]);

One more example: creating an issue, including setting the Priority field using dynamic:
dynamic issue = new Issue
{
    Summary = "I have issues!",
    Description = "Here's one more."
};

issue.Priority = "High";

await issuesService.CreateIssue("PROJ", issue);

Maybe one more? What about time tracking for an issue:
var timeTrackingService = connection.CreateTimeTrackingService();

await timeTrackingService.CreateWorkItemForIssue("PROJ-123",
    new WorkItem(DateTime.UtcNow, TimeSpan.FromHours(2), "Writing blog post"));

Available REST API’s

YouTrackSharp provides several services we can work with:

Next to these, we have also added the various color indices available in YouTrack. We can use the ColorIndices class which maps the index to a foreground and background color, or use the (hex) colors exposed on the field directly:

var priorityField = issue.GetField("Priority");
                
Console.WriteLine("Priority: {0} (foreground {1}, background {2})",
    priorityField.AsString(),
    priorityField.Color.Foreground,
    priorityField.Color.Background);

What about other languages?

While YouTrackSharp focuses on the various .NET languages like C#, VB.NET and F#, there are YouTrack API wrappers for languages as well. A quick search on libraries.io shows Java and Kotlin, PHP, JavaScript, Python and Ruby.

Give the new YouTrackSharp a try, and let us know how it goes! If you feel like contributing, feel free to tackle one of the UpForGrabs issues and help make YouTrackSharp better!

Beta integration JetBrains REST API Search YouTrackSharp
Live Webinar: Introduction to JavaScript Workflows in YouTrack 2017.3YouTrack 2017.3 is Released!
Comments below can no longer be edited.

7 Responses to YouTrackSharp 3.0 beta – A .NET Standard Client for YouTrack

  1. Avatar

    Robert Wright says:

    September 5, 2017

    Hi Maarten,

    I’m trying to use the new version of the API v3.0.1 and I’m getting an error when trying to get the list of projects that I have access to using the below code:-

    var issuesService = connection.CreateIssuesService();
    var sprintIssues = await issuesService.GetIssuesInProject(“Everything”, null, null, 99, null, false);

    But I’m getting an error when I make the call with the await keyword :-
    “Unexpected character encountered while parsing value: <. Path '', line 0, position 0."

    I'm want to print out the issues so we can use a physical sprint board.

    I'm using Newtonsoft.Json v10.0.0.0
    .Net Framework 4.6
    Visual Studio 2017 v15.2

    Any help would be greatly appreciated.

    Cheers
    Robert

  2. Avatar

    David Refaeli says:

    November 14, 2017

    Does the old syntax not supported anymore? I have a 4.5 .NET Framework app, and I can’t install YouTrackSharp 3.0, only 2.0.

    I try to use the old syntax:
    var connection = new Connection(“xxxx.myjetbrains.com”, 80, false, “youtrack”);
    connection.Authenticate(“xxxxx”, “xxxxxx”);

    And it tells me “Method not allowed”;

    If I try only new Connection(“xxxx.myjetbrains.com”) it throws an error:

    “For security reasons DTD is prohibited in this XML document. To enable DTD processing set the DtdProcessing property on XmlReaderSettings to Parse and pass the settings into XmlReader.Create method.”

  3. Avatar

    Jiri says:

    June 10, 2020

    Thanks a lot for great page with guidance. It helps me a lot with my first steps with YT.
    Just to share my experience – In the code snippet 2 I have to add the Result method to the second line to make it working. So the line:
    var issues = await issuesService.GetIssuesInProject(“PROJ”, take: 250);
    has to be changed to:
    var issues = await issuesService.GetIssuesInProject(“PROJ”, take: 250).Result;
    Hopefully it helps others.

Discover more

Manage Product Requirements with YouTrack Knowledge Base

Lots of development, marketing, product, and project teams are using YouTrack to deliver great products. This requires an effective process for managing product requirements. The typical process involves creating user stories and epics, using a project overview with Gantt charts, tracking feature requests publicly and internally, fixing bugs, and collaborating with other teams on issues. Now, ther

Anastasia Bartasheva Anastasia Bartasheva

YouTrack now with Knowledge Base

You can read this post in English, French, Russian, Korean, Chinese, Japanese, Brazilian Portuguese, and Spanish. We are excited to announce the release of YouTrack 2020.2 which comes with a built-in Knowledge Base! Now you can build a public knowledge base and keep internal documentation right inside YouTrack, alongside your tasks and projects. YouTrack can keep your team’s collective know

Anastasia Bartasheva Anastasia Bartasheva

YouTrack now with Reactions 😀

Read this post in other languages:     We are happy to release YouTrack 2020.1! And now, there is a way to express this happiness, and many other emotions, with emoji reactions. 😀 What’s more, you won’t miss any reactions thanks to reaction notifications we’ve introduced. In other enhancements, in-context translation right from the user interface is now available for anyone who wan

Elena Pishkova Elena Pishkova

Legacy TLS Protocols Deprecation Warning for YouTrack InCloud

The information in this post is primarily for administrators of YouTrack InCloud instances. We want to let you know that we’re about to introduce some changes that will come into effect on March 1, 2020. In the meantime, we recommend checking your users’ browser versions and the settings of your REST API integrations. (more…)

Elena Pishkova Elena Pishkova