YouTrack
Powerful project management for all your teams
YouTrackSharp 3.0 beta – A .NET Standard Client for YouTrack
Please 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:
- User-related methods through
UserService
- Projects-related methods through
ProjectsService
- Issues-related methods through
IssuesService
- Time-tracking-related methods through
TimeTrackingService
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!