MantisSharp is a .NET client for the Mantis Bug Tracker REST API.
Important! This project is very much at the "Work In Progress" stage. You probably don't want to rely on it for anything important. Contributions welcome!
You need to enable pre-release in order to see this package from the NuGet package manager
install-package MantisSharp -Pre
The package currently includes .NET 3.5, 4.0, 4.5 and 4.6 binaries. I was going to include 4.7 until I realised I'd defered the Creators Content update and Microsoft won't let you target 4.7 without upgrading. And I definitely want to include .NET Standard support but I'll need to fumble around a bit more first.
If you just want to use the source, MantisSharp.sln can be opened using Visual Studio 2017, MantisSharp.csproj is using the new format and does all the multi-targeting and the NuGet packing. MantisSharp_vs2015.sln uses the slightly more old school format and can be opened using Visual Studio 2015. All projects with a _vs2015 suffix are for mainly for development purposes only, I built the release library using VS2017.
MantisSharp is currently self contained and doesn't depend on any third party libraries - ideally I'd like to keep it that way, even if it does require some wheel re-inventing.
To use the client, you're going to need a Mantis installation with the REST API enabled (it is disabled by default). In addition, you're going to need to have created a token for use with the API. I'd recommend creating a dedicated "restuser" type of account with no write permissions. Impersonate that user, generate a token to use, then switch by to an admin account and protect the user.
Note that the type of user (e.g.
viewerordeveloper) greatly affect the amount of information returned via the REST API, and in some cases affect the functionality - for example, by default theviewerrole can't access filters.
The REST client was introduced into MantisBT in version 2.3, however I have only tested using 2.5.1 (at the time of writing, this is the current version). Once a successful connection has been made, you can use the MantisVersion property of the client object to find out what version the server is reporting.
At this stage of the libraries existence, there are plenty of limitations - see the Todo section below for details.
The REST API offered by MantisBT is also bit limited at the moment. It doesn't provide access to all information, and while you can create or delete issues (neither of which are offered by this library at the current time), you cannot update issues. It also doesn't provide access to a definitive list of all the different meta data that is available. But if you want to read most project and issue information then we've got you covered.
First you need to create a MantisClient object and pass in the base URI where your MantisBT installation is hosted, along with an API key.
MantisClient client = new MantisClient("YOUR_MANTIS_URI", "YOUR_API_KEY");
An API key simply links to a given user account, so you can create multiple accounts with different roles/permissions and then use the most restrictive keys required for a given job.
I haven't done any documentation for this library yet so these instructions are a little sparse. There is a sample WinForms application for browsing data that may be of help.
The GetProjects method will return the projects available to the API user
foreach (Project project in client.GetProjects())
{
Console.WriteLine(project.Name);
}
The GetIssues method returns issues. You can return all issues, or pass in project information to filter by project.
foreach (Issue issue in client.GetIssues())
{
Console.WriteLine(issue.Summary);
}
Or, you can grab issues for a specific project
var issues = client.GetIssues(4); // or pass in a Project reference
There are also overloads which let you page results, but given there doesn't seem to be a simple way to get an upfront count this functionality is a little useless right now
You can also grab a single issue
Issue issue = client.GetIssue(52);
To delete a single issue
client.DeleteIssue(52);
Currently the only supported feature of the MantisBT REST API is to return details of the user associated with the API token.
User user = client.GetCurrentUser();
The following table lists how much of the REST API is currently covered. (There are no actions using PATCH or PUT verbs in the API).
| API | DELETE | GET | POST | Notes |
|---|---|---|---|---|
/config |
n/a | Yes | n/a | |
/issues |
Yes | Yes | Yes | Get supports all, single issue, paging and specifying a filter |
/lang |
n/a | No | n/a | Returns no data for my instance. |
/projects |
n/a | Yes | n/a | |
/users |
n/a | Yes | n/a | Underlying API only supports returning data for the current user |
This is an abridged version of code I used to produce a roadmap from an ASP.NET application.
Project project;
Issue[] issues;
MantisClient client;
client = new MantisClient(SiteConfiguration.MantisBaseUri, SiteConfiguration.MantisApiKey);
project = client.GetProject(product.MantisProjectId);
issues = client.GetIssues(project).ToArray();
return this.View(new ProductRoadmapModel
{
Product = product,
Project = project,
Issues = issues
});
@using MantisSharp
@model ProductRoadmapModel
@{
Product product;
Project project;
Issue[] issues;
product = Model.Product;
project = Model.Project;
issues = Model.Issues;
}
@if (project != null)
{
ProjectVersion[] versions;
versions = project.Versions.Where(version => !version.Released).OrderBy(version => version.Timestamp).ToArray();
if (versions.Length > 0)
{
foreach (ProjectVersion version in versions)
{
Issue[] versionIssues;
versionIssues = issues.Where(issue => issue.TargetVersion != null && issue.TargetVersion.Id == version.Id).ToArray();
@Html.Header(2, version.Name)
if (versionIssues.Length > 0)
{
<ul class="list-unstyled">
@foreach (Issue issue in versionIssues)
{
<li>
<i class="fa fa-square fa-status-box" style="color: @issue.Status.Color" title="@issue.Status.Label"></i>
<span class="label-light">[@issue.Category.Name]</span> @issue.Summary
</li>
}
</ul>
}
else
{
<p>No issues found.</p>
}
}
}
else
{
<p>There are no pending versions available to display.</p>
}
}
- Documentation
- Async support
- Use something a little more modern than
HttpWebRequest - .NET Standard support
- Ability to write back to MantisBT
- Add .NET 4.7 target
- Figure out Nuget woes
- Tests
- Performance
- Finalize API
- Rework serialization to be lessy hacky
- Error handling - asking for issues that don't exist for example
- The MantisBT for giving access to the REST API
- Topten Software for their utterly awesome PetaJson which I'm using in a not so awesome fashion.
- Graphics in the Browser sample are from the Visual Studio Image Library.