Skip to content
A fully object-oriented .Net wrapper for Trello's RESTful API written in C#.
Branch: master
Clone or download
Latest commit b77f7a6 Jul 12, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github added funding details Jul 12, 2019
Logo Legal Updated Labels implementation to support Trello's changes to provide … Nov 30, 2014
Manatee.Trello.CustomFields multi-targeted. boom! Apr 19, 2018
Manatee.Trello.IntegrationTests custom fields don't download on boards as a nested resource May 22, 2019
Manatee.Trello.Tests.Common added query params to collection requests Sep 15, 2018
Manatee.Trello.UnitTests ignore dev test; updated version & release notes May 22, 2019
Manatee.Trello custom fields don't download on boards as a nested resource May 22, 2019
Resources updated slack logo May 4, 2018
Tools defined emoji and generated library static class Mar 2, 2019
docs updated docs May 22, 2019
docs_source ignore dev test; updated version & release notes May 22, 2019
.gitignore added currency to license doc May 29, 2018
Endpoint definitions.xlsx BUG FIX: Webhook not downloading. Apr 15, 2014
LICENSE.txt mostly done. waiting for a dependency. Sep 19, 2017
Manatee.Trello.sln updated release notes and documentation May 10, 2018
Manatee.Trello.sln.DotSettings implementation done Mar 3, 2019
Manatee.Trello.sln.DotSettings.user added new user Feb 15, 2019
Manatee.Trello.userprefs Added stock sticker support. Oct 9, 2014
Manatee.Trello.v12.suo BUG FIX: AttachmentCollection throws when adding via URL. Aug 9, 2016
Manatee.Trello.vsmdi Major architectural changes to support Store and Forward feature. Jul 9, 2013
README.md added ko-fi link Jul 12, 2019
RELEASE NOTES.md Fix link to release notes Nov 29, 2018
appveyor.yml updated build script Jan 16, 2018
build.bat testing env var for user token Apr 30, 2018
nuget-restore.ps1 update package script Jan 15, 2018

README.md

Manatee.Trello

NuGet version (Manatee.Trello) Build status MyGet Build Status Percentage of issues still open Average time to resolve an issue

Discuss on Slack

ReSharper

The primary goal of Manatee.Trello is to provide an intuitive, object-oriented representation of Trello entities. Other API wrappers that I encounter contain service objects with functions that return little more than non-functional DTOs (data transfer objects) to represent the entities.

The architecture of Manatee.Trello ensures:

  • All data is exposed in an intuitive manner
  • API calls are minimized
  • A safe multithreading experience
  • Full configurability

Setup

Before any data is retrieved, some configuration is required. It's fairly simple:

TrelloAuthorization.Default.AppKey = "[your application key]";
TrelloAuthorization.Default.UserToken = "[your user token]";

This will initialize using the libraries linked above.

Reading data

Most entities can be accessed directly simply by:

  1. calling their constructors and passing the entity's ID.

    var board = new Board("[your board id]");
  2. calling the corresponding method on the TrelloFactory class.

    ITrelloFactory factory = new TrelloFactory();
    var board = factory.Board("[your board id]");

NOTE The entity contructors and the factory methods can work with both a long and short ID. The short IDs for boards and cards are pretty easy to find, too: they're in the URL! For example, the Trello API Changelog board (https://trello.com/b/dQHqCohZ/trello-platform-changelog) has a short ID of dQHqCohZ. The long IDs can be found in the Id property of any of the entities; they're not exposed through the website in any way.

Once you have an entity, you can get any entities related to it through its properties or extension methods.

var cards = board.Cards;

Minimizing API calls

Manatee.Trello holds requests to the API until data is actually requested. This means that with the above code, no calls have yet been made, even though we have created a board and accessed its collection of cards.

It's not until we attempt to read/write data about the board or enumerate the card collection that a request will be made.

For example, let's take a look at the following code snippet:

ITrelloFactory factory = new TrelloFactory();
string boardId = "[a board ID]";
var board = factory.List(listId);
await board.Refresh();
var list = board.Lists.First();
var card = list.Cards.Add("new card");
var member = board.Members.First();
card.Members.Add(member);

There are three calls being made here:

  • Download the board (also downloads members, lists, and a host of other information)
  • Add a card to the first list
  • Assign a member to the card

In addition to the above optimizations, Manatee.Trello will consolidate multiple rapid changes to the same object into a single call. So the following code snippet only produces a single call:

card.Name = "A New Hope";
card.Description = "The original Star Wars film is still considered by many to be the best of the entire series.";
card.DueDate = DateTime.Now;

NOTE The limit here is that this only supports direct changes to the card object itself. Collections on the card (such as Checklists are considered separate objects and additional calls will be made for these changes.

On top of all of this, Manatee.Trello maintains an internal cache (for which you can supply your own implementation, if you choose) that holds every entity that has been downloaded. Any time one entity references another that has already been cached, the cached entity is used rather than downloading and instantiating a copy.

Lastly, each entity will automatically update itself on-demand, throttled by a configurable timeout. So, if it's been a while since you checked the name of a card and someone has updated it online, the card will automatically refresh.

Of course, all of this functionality is configurable and completely abstracted from you, the client.

Additional Features

Features:

  • Supports:
    • .Net Framework 4.5
    • .Net Standard 1.3
    • .Net Standard 2.0
  • Fully asynchronous implementation
  • Full customization of data management (download only what you need)
  • Data upload aggregation (set multiple properties on an entity with a single call)
  • All collections are LINQ-compatible
  • All entities implement interfaces to support unit testing & dependency injection
  • Extensible framework to support Trello PowerUps
  • CustomFields, Voting, and Card Aging PowerUps built in (must be enabled on the board)
  • Supports simultaneous usage of multiple Trello accounts
  • Entity caching to avoid unnecessary duplication of entities
  • Seams available for providing custom implementations of:
    • Cache
    • REST client
    • JSON serializer
  • Webhook integration
  • Update notification via .Net events
  • Batch downloads
  • Functions:
    • Boards
      • Add/Edit/Delete
      • Add/Edit board-wide preferences & permissions
      • Add/Edit personal preferences
      • Add/Remove members
      • Add/Edit/Delete custom fields
      • Add/Remove to/from organization
      • Enable/Disable power-ups
      • Set custom backgrounds
    • Lists
      • Add/Edit/Reorder
      • Move to board
    • Cards
      • Add/Copy/Edit/Delete/Reorder
      • Add/Edit/Clear custom field data
      • Add/Edit/Remove stickers
      • Add/Edit/Delete comments
      • Add/Copy/Edit/Delete/Reorder checklists
      • Add/Edit/Delete/Reorder checklist items
      • Show/Hide custom fields on cover
      • Move to list
    • Organizations (Teams)
      • Add/Edit/Delete
      • Read/Set org-wide preferences & permissions
      • Add/Remove members
      • Add/Edit/Clear custom field data
    • Members
      • Read public member data
      • Read/Update authenticated member data
      • Read notifications for authenticated member
      • Read custom board backgrounds
      • Delete custom board backgrounds for authenticated member
    • PowerUps
      • Provided base class
    • Searches
      • General search
      • Member search
      • Refresh to rerun query
    • Tokens
      • Read/Delete
    • Webhooks
      • Add/Edit/Delete

See the docs for more information on how to use this wonderful library!

Extended use

As of version 3, a licensing model has been introduced.

If you're planning on using this for your organization, please consider purchasing a license.

Contributing

If you have questions, experience problems, or feature ideas, please create an issue.

If you'd like to help out with the code, please feel free to fork and create a pull request.

The Project

This code uses C# 7 features, so a compiler/IDE that supports these features is required.

The solution consists of a multi-targeted project and .Net Framework 4.6.2 test projects.

Building

During development, building within Visual Studio should be fine.

To run the tests, you'll need to store your user token in an environment variable called TRELLO_USER_TOKEN.

Code style and maintenance

I use Jetbrains Resharper in Visual Studio to maintain the code style (and for many of the other things that it does). The solution is set up with team style settings, so if you're using Resharper the settings should automatically load. Please follow the suggestions.

Appreciation

If you've enjoyed using this library and you'd like to contribute financially but don't need a license, please use the button below.

Donate

You can’t perform that action at this time.