Recently I created my first XrmToolBox plugin User Security Manager and successfully released this to the plugin store. I followed XrmToolBox for developers and the other resources available on the internet but creating a plugin was not so smooth for me, so I thought of writing my experiences and detailed step by step guide.
I will detail the entire process in 4 different blogs this is my first blog in this series.
- Create XrmToolBox Plugin – Part 2: Debug XrmToolBox Plugin
- Create XrmToolBox Plugin – Part 3: Package your plugin
- Create XrmToolBox Plugin – Part 4: Setup build definition release fo CI and CD
- Visual Studio 2017
Step 1: Download and install XrmToolBox Plugin Project Template: download VS 2017 project template and install on your dev machine.
Step 2: Open VS 2017 and go to File -> New -> Project…, it will open a new project window.
- Click on “Installed” (1) template and search for “Xrm” (2). You will see the above-installed plugin (3).
- Give a meaning full name to your plugin (4) and click OK(5).
- Click on “Trust” if you get following warning message.
Update Plugin Metadata open file “MyPlugin.cs” and update the following metadata details
- Name: Name of your plugin. It will appear in XrmToolBox plugin list and plugin store.
- Description: Short description of your plugin. It will appear in XrmToolBox plugin list and plugin store.
- SmallImageBase64: 32*32 logo of your plugin, to generate a base64 string of your plugin logo you can use this URL.
- BigImageBase64: 80*80 logo of your plugin, to generate a base64 string of your plugin logo you can use this URL.
- BackgroundColor: background color of your plugin
- PrimaryFontColor: Primary font color of your plugin
- SecondaryFontColor: Secondary font color of your plugin
Step 4: Build your plugin logic At this point you are all set to start building your logic into the plugin. You can create UI and add code logic but still, you cannot run/debug it. In my next blog I will talk about debugging, but before we go there let’s elaborate on the various components of this project, do’s and don’ts. (below is how default project structure will look like)
- MyPlugin.cs: This file contains all necessary metadata that defines your plugin, please make sure you have provided all the values in this file as described above.
MyPluginControl.cs: all your plugin logic goes here or gets invoked from here.
- If your plugin logic is simple and does not requires much coding you can put everything in this class file (this is just my opinion).
- If your plugin logic is complex, and you are using some design pattern then this is the class where you will initialize your child components, controls.
MyPluginControl_Load: You can put your initializing logic here. Like configuring the plugin as per the user settings, or resuming the plugin last used state etc.
MyPluginControl_OnCloseTool: Your plugin close logic (if any) goes here.
UpdateConnection: If you want to configure the behavior of your plugin on change of CRM connection, then you need to inject your logic here. For example, if you want to reload data from new CRM organization on XrmToolBox connection change, you can invoke that logic from this function.
If your plugin needs multiple organization connections (one such example is if you are creating a plugin to move data from once CRM org to another CRM org), then you need to inherit “MultipleConnectionsPluginControlBase” class and implement “ConnectionDetailsUpdated” method. By default “MyPluginControl” class inherits “PluginControlBase” base call which provides access to only one Organization connection at a time.
If you inherit “MultipleConnectionPluginControlBase” then you need to implement “ConnectionDetailsUpdate”
Do’s and Don’ts:
- To ensure that Organization service is available when you execute your logic use “Service.Execute(<<your function name>>());” instead of invoking you function directly.
- Your plugin logic should be asynchronous, it should not block the tool itself. Use function “WorkAsync” and class “WorkAsyncInfo” to invoke your logic asynchronously, for details see here.
- Add proper logging to your plugin. “PluginControlBase” class provides 3 helper methods that you can use.
- Do not use early bound classes with your plugin.
- Your plugin should open with or with or without a connection available in XrmToolBox.
Hope It helps. In the next blog, I will explain how to debug your plugin in visual studio.