Version 2.0 Migration Guide #51
Description
Breaking changes
In version 2.0, the following breaking changes are introduced to streamline the API and make it more future-proof by moving most parameters to option-objects instead. All Breaking changes are listed below (and if something be missing, feel free to comment below)
It is recommended that you first upgrade to the latest version 1.x release, Resolve all [Obsolete] warnings, and then move to 2.x (that way you can gauge how big the migration will be and be guided directly in code by the obsolete warnings)
If you rather want to watch instead of read then here is the video version of this migration guide
TrelloClient.cs
Public method renames to fix missing the Async suffixes
| 1.x | 2.x |
|---|---|
| GetBoardsInOrganization | GetBoardsInOrganizationAsync |
| GetCommentReactions | GetCommentReactionsAsync |
| GetTrelloPlanInformationForBoard | GetTrelloPlanInformationForBoardAsync |
| GetTrelloPlanInformationForOrganization | GetTrelloPlanInformationForOrganizationAsync |
| MoveCardToBoard | MoveCardToBoardAsync |
The following methods all received an Async suffix to keep all public names consistent (it was a bug that they were not renamed this way in the first place!) - An .editorconfig is now in place to prevent this from happening going forward
Removed AddCardAsync(Card card)
Use this instead: AddCardAsync(AddCardOptions options)
While working, this was limited to only a subset of the Fields a Card could have, and you needed to make subsequent calls to set things like Checklists, Attachments, etc. On top of that, since the input was the same object as the output it was impossible to describe the properties properly for an Add-scenario, and it was also confusing that the input card should not be used anymore after the addition. The new method resolves all these pain points and allows you to set every single field on a Trello Card in one call, and should be fairly simple to migrate to, as you just need to turn new Card(...) into new AddCardOptions(...)
Removed AddCardTemplateAsync(Card card)
Use this instead: AddCardAsync(AddCardOptions options) with options.IsTemplate
It felt redundant to have this separate method for this now that AddCardAsync(AddCardOptions options) can set all fields so removed to streamline the API
Removed UpdateCardAsync(Card cardWithChanges)
Use this instead: UpdateCardAsync(string cardId, List<CardUpdate> valuesToUpdate)
The original UpdateCard method had 2 serious issues that warranted its removal despite it being a rather hard migration. Firstly, its performance was poor since it essentially 'updated' all fields and not just the delta updates (especially bad if you had very long descriptions on the card you updated). This secondarily meant that since this was not a delta update, any changes between you retrieved the card and your update were lost! UpdateCardAsync(string cardId, List<CardUpdate> valuesToUpdate) you instead only provide the actual changes resulting in much better performance and no chance for loss of data 🙌
Removed UpdateCardAsync(string cardId, List<QueryParameter> parameters...)
Use this instead: UpdateCardAsync(string cardId, List<CardUpdate> valuesToUpdate)
This was a prior attempt to resolve the full vs delta update. While it succeeded, it was a much too 'nerdy' version of UpdateCardAsync(string cardId, List<CardUpdate> valuesToUpdate) that required you to know technical names and values of the core Trello REST API, making it too hard to use.
Removed GetCardsOnBoardFilteredAsync()
Use this instead: GetCardsOnBoardAsync(string boardId, GetCardOptions options) with options.Filter = <your filter>
To streamline and prepare for future features, the dedicated 'Filter' version was removed
Removed GetListsOnBoardFilteredAsync()
Use this instead: GetListsOnBoardAsync(string boardId, GetListOptions options) with options.Filter = <your filter>
To streamline and prepare for future features, the dedicated 'Filter' version was removed
Removed various GetActions...(string id, List<string> filter = null, int limit = 50) variants
GetActionsOfBoardAsync(string boardId, List<string> filter = null, int limit = 50)replaced by GetActionsOfBoardAsync(string boardId, GetActionsOptions options)GetActionsOnCardAsync(string cardId, List<string> filter = null, int limit = 50)replaced by GetActionsOnCardAsync(string cardId, GetActionsOptions options)GetActionsForListAsync(string listed, List<string> filter = null, int limit = 50)replaced by GetActionsForListAsync(string listId, GetActionsOptions options)GetActionsForMemberAsync(string memberId, List<string> filter = null, int limit = 50)replaced by GetActionsForMemberAsync(string memberId, GetActionsOptions options)GetActionsForOrganizationsAsync(string organizationId, List<string> filter = null, int limit = 50)replaced by GetActionsForOrganizationsAsync(string organizationId, GetActionsOptions options)
Having the parameters for getting the actions directly on the method, prevented extension without breaking changes, so these variants were removed to support Pagination (and future enhancements)
TrelloClientOptions.cs
Removed TrelloClientOptions (Non-Empty Constructor)
Use this instead: Use the empty Constructor and set each value you wish to deviate from the default
Having this non-empty constructor meant that whenever a new option needed to be added, it was a breaking change, and since two of the options in it was scheduled to be removed as well, I opted for an empty constructor instead, where you instead only set values for you want to deviate from the defaults
Removed IncludeCustomFieldsInCardGetMethods (Property)
Use this instead: Use GetCardOptions to define this in the various GetCard Methods
This was an early flawed attempt of adding the Include extra data option. Having it centrally instead of on the individual methods was cumbersome, not discoverable, and led to poor performance if just set on everything, so it was removed
Removed IncludeAttachmentsInCardGetMethods (Property)
Use this instead: Use GetCardOptions to define this in the various GetCard Methods
This was an early flawed attempt to add the Include extra data option. Having it centrally instead of on the individual methods was cumbersome, not discoverable, and led to poor performance if just set on everything, so it was removed