Major update to XrmToolBox Shared Controls
I’ve published several posts about shared XrmToolBox controls, starting with this post several months ago: Shared XrmToolbox Controls: Entities List View. Since then, I’ve made updates and added new controls to the repository, such as updates to the EntitiesListView and an additional EntitiesDropdown control.
So far, I’ve received some great feedback. Michael Ochs released his own XrmToolBox Tool Dynamics 365 Universal Search for XrmToolBox that leveraged the EntitiesListView control. Jonas Rapp also presented a session at 365 Saturday Stockholm titled Let’s build an XrmToolBox tool! where he used my EntitiesDropdown control and with his Grid control to build an XrmToolBox tool from scratch on the spot. Jonas just posted We create XrmToolBox tools at Dynamics 365 Saturdays! where he talks about this event and building XrmToolBox tools. What better way to test your components than have smart people use them!
This initial set of controls had a hard dependency on on the XrmToolBox extensibility with the reference to the parent Tool control derived from PluginControlBase. The reason for this was to allow my controls to leverage the parent control PluginControlBase properties and methods, such as the WorkAsync method and Service instance. While discussing the design with Jonas, he suggested I remove the dependency so that the controls offer more flexiblity in their use. This made sense… For example, I may want to place the control on a form that is not your Tool control?
Time for some changes!
The New Repository
Removing the dependencies was not a huge overhaul of the controls. But because these changes break Tools for those using the controls, I decided to make a new GitHub repository and do some other refactoring. So I will be leaving the old repository in place for those that wish to use it and I started a brand new repository: xrmtb.XrmToolBox.Controls
The first change was to remove the dependency on the XrmToolBox packages. This was a breaking change on the Initialize method required for the old controls and some of the . This meant removing the XrmToolBoxPackage and the related MscrmTools.Xrm.Connection NuGet packages from the solution. Luckily enough, the project still compiled!
The biggest impact of this change came with the OrganizationService calls in loading the CRM data and metadata. For example, when loading the list of Entities in the EntitiesListView control, I needed to implement the Background worker thread logic myself that was so nicely provided by the WorkAsync method on the PluginControlBase class. This ensured that my controls do not lock up the screen when used by a Tool.
Another impact of this change is the new set of controls can theoretically be used for any WinForm project. All you would need to do is provide an OrganizationService connection to the control and it should work! I plan on testing this out with the project soon.
New design and additional Tools
The underlying design with my original controls should remain the same. Each control implements a shared interface, IXrmToolBoxControl. This interface is relatively straightforward, providing a set of common methods and related event definitions that clients can expect, such as the LoadData method and related BeginLoadData and EndLoadData events. I’ve added a few new items to the list, such as NotificationMessage event and a related enum to distinguish between Info, Warning, and Error messages. The Tool using the control can decide how to handle these notification events.
Common properties on the IXrmToolBoxControl interface have been updated. The Service property and UpdateConnection method remain but the ParentBaseControl property no longer applies. A new property AutoLoadData can be helpful to indicate whether the data should be loaded as soon as the Service reference is available. A LanguageCode property has also been applied for controls that might work with different languages.
I also took some time to overhaul the underlying controls themselves. This meant refactoring existing and creating several new controls. I had a bit of a pattern with a ListView based control and a comparable Dropdown control in my original repository. I realized that the “pattern” for the EntitiesListView and EntitiesDropdown controls could be replicated for different CRM data or metatada.
All your base…
This review and refactoring effort resulted in two new base User Controls, the XrmToolBoxControlBase and FilteredListViewBaseControl.
The XrmToolBoxControlBase is pretty simple in that it wraps up some common methods around raising the events and locking down the controls when no Service reference is available. Simple, but it saves a lot of copy and paste code.
The EntitiesListView control is a bit more complex but offered a nice template for other controls requiring similar functionality, such as binding some data to a ListView that supports filtering and sorting. An AttributeListView control immediately comes to mind. So I refactored the code into FilteredListViewBaseControl. This is a base control that provides the base functionality for binding a generic list of items to a ListView, sorting, filtering, checking items, etc. This includes the optional toolbar at the top of the control that includes some UI elements for these features.
Once I created this base control, I was able to create two new controls in a matter of a few hours!
The Updated List
With the overhaul of the design and the new base controls, I was able to add a few additional controls to the repository The updated list of available tools is now:
- EntitiesListView – load a ListView of Entities in CRM instance or for a given Solution. Includes filtering by name and schema name, sorting, checking multiple items, and filtering by Solution
- EntitiesDropdown – load a Dropdown of Entities in the system or for a given Solution
- AttributeListView – load a Attributes for a given Entity. Includes filtering by name and schema name, sorting, checking multiple items
- AttributeDropdown – load a Dropdown of Attributes for a given Entity
- SolutionsDropdown – load a Dropdown of Solutions in a CRM instance
- ViewsDropdown – load a list of Views for a given Entity. Allows filtering by system only or both system and personal views
- GlobalOptionSetList – load a ListView of all Global OptionSets in a CRM instance
- XrmToolBoxControlBase – base control for implementing your own XrmToolBox shared control
- FilteredListViewBase – base control for implementing your own
ListView style XrmToolBox shared control
- CrmGridView – control extending the WinForm Data grid that allows displaying a list of Entities. This control was developed by Jonas as part of the
Cinteros.Xrm.CRMWinFormNuGet package and he’s offered to add it to the repository!
That’s right… We have a contribution by Jonas in the repository now! I’m really excited to have his eyes on the design and his suggestions on how to improve and manage the set of shared controls.
More to come on this list outside of the common ListView and Dropdown style controls, but these should help someone building an XrmToolBox tool that requires interacting with CRM metadata.
Some Issues and a To Do list
With the overhaul come some issues. Currently, I am working through an issue with ILMerge. When using the controls in a Tool, you will need to reference the code directly. Fortunately, Daryl LaBar has suggested and actually provided a Code only NuGet package for the project. This means instead of referencing the assembly, you can reference the code directly as part of your project.
Another item is more of a To Do list item. The LanguageCode property is available but I need to ensure that all of the controls properly handle this property. Some of the controls handle things properly, while others need some work.
Another big change was to remove the Futurez branding from the namespace. I am very proud of the work on the controls and I love the self promotion (yeah, Futurez!), but my longer term goal is to provide a library of controls for everyone to use. So I am looking to add some other Tool developers controls to the repository in the near future. We already have the killer CrmGridView control added by Jonas!
A long term goals for building these controls was to have them included as part of the XrmToolBox extensibility libraries. I am very excited to be working with Tanguy to make this happen. He and the other contributors will first need to validate my design to ensure no issues arise with the platform or other Tools. This would get past any need for developers to use ILMerge since the controls would be included with the base install. But more importantly, I would have my overall design signed off by the XrmToolBox team! I have some work to do to make this happen, so I will drop a post when that release is planned.
More to come
Keep an eye out for a few more posts as I add some polish to the controls and add a few new items. I will also be deploying the code only NuGet package soon and updating the documentation in the new Github repository. Stay tuned!