{"id":316,"date":"2022-12-09T15:59:46","date_gmt":"2022-12-09T13:59:46","guid":{"rendered":"https:\/\/www.kogero.hu\/?p=316"},"modified":"2022-12-31T11:52:41","modified_gmt":"2022-12-31T09:52:41","slug":"plugin-irasa-dataverse-hez","status":"publish","type":"post","link":"https:\/\/www.kogero.hu\/en\/2022\/12\/09\/plugin-irasa-dataverse-hez\/","title":{"rendered":"Create plugin in Dataverse"},"content":{"rendered":"

<\/p>\r\n

In this post I will show you how to write a plugin from scratch for Power Apps model-driven applications like Dynamics 365 or other custom built applications. It can happen you reach the limits of no-code solutions and you need to extend the OOB functionality with custom business logic. In this example we create a plugin, which will copy a telephone number to a contact record from the related account record. But what is a plugin? A plugin is a piece of code written in C# that can be compiled to a DLL file, then uploaded to Dataverse and bound to different events to be executed. I try to explain step-by-step to make it understandable for juniors and citizen developers as well.<\/p>\r\n

\r\n\r\n<\/p>\r\n

Execution Pipeline in Dataverse<\/h3>\r\n

\r\n\r\n<\/p>\r\n

Before we jump in it, first I need to mention some words about the “Event Framework” to make clear how and when our code can run, which is provided by Dataverse. It helps us to bind our code to run on specific events e.g. creating, updating, deleting, retrieving a record in the system and we can also define more precisely when to run: before our record is being saved or after that. For this we can use 3 stages of 4:<\/p>\r\n

\r\n\r\n<\/p>\r\n

\"Event\r\n
Event Execution Pipeline (source<\/a>)<\/figcaption>\r\n<\/figure>\r\n

\r\n\r\n<\/p>\r\n

\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n
Name<\/th>\r\nDescription<\/th>\r\n<\/tr>\r\n<\/thead>\r\n
PreValidation<\/td>\r\nIn the first stage we can validate user privileges and input data, and we can easily return error message for the user.<\/td>\r\n<\/tr>\r\n
PreOperation<\/td>\r\nHere we can make changes, which are already inside database transaction and will be rolled back in case of any errors. Roll backs are resource intensive operations, so do not do data validations here.<\/td>\r\n<\/tr>\r\n
MainOperation<\/td>\r\nMain Operation where our changes are being saved to database.<\/td>\r\n<\/tr>\r\n
PostOperation<\/td>\r\nOperation after saving changes.
Important note: asynchronous plugins must be run in this operation.<\/td>\r\n<\/tr>\r\n<\/tbody>\r\n<\/table>\r\n
Execution pipeline<\/figcaption>\r\n<\/figure>\r\n

\r\n\r\n<\/p>\r\n

Create Project in Visual Studio 2022<\/h2>\r\n

\r\n\r\n<\/p>\r\n

Create a project by selecting template “Class Library (.NET Framework)”:<\/p>\r\n

\r\n\r\n<\/p>\r\n

\"Create\r\n
Creating new Project<\/figcaption>\r\n<\/figure>\r\n

\r\n\r\n<\/p>\r\n

Select framework “.NET Framework 4.6.2”:<\/p>\r\n

\r\n\r\n<\/p>\r\n

\"Configure\r\n
Configure new Project<\/figcaption>\r\n<\/figure>\r\n

\r\n\r\n<\/p>\r\n

After creating the project we need to install the SDK that we have to use for developing the plugin: install “Microsoft.CrmSdk.CoreAssembly” NuGet package.<\/p>\r\n

\r\n\r\n<\/p>\r\n

\"Install\r\n
Install SDK from NuGet<\/figcaption>\r\n<\/figure>\r\n

\r\n\r\n<\/p>\r\n

Write Business Logic for Plugin<\/h2>\r\n

\r\n\r\n<\/p>\r\n

The previously installed SDK contains “Xrm.Sdk”-t, which provides the basic objects and interfaces to connect to Dataverse and make operations.<\/p>\r\n

\r\n\r\n<\/p>\r\n

Create a new class in the project and add “using Microsoft.Xrm.Sdk;” on top.<\/p>\r\n

\r\n\r\n<\/p>\r\n

IPlugin interface<\/h3>\r\n

\r\n\r\n<\/p>\r\n

When we are creating a new plugin we need to implement an interface “IPlugin”, which contains a method “Execute”, and by its input parameter it can get the execution context and services. Organization Service (“IOrganizationService”) is one of the most used service in plugins. Important note that all the classes which implement “IPlugin” interface will be found as plugin in the Plugin Registration Tool.<\/p>\r\n

\r\n\r\n<\/p>\r\n

The interface “IPluginExecutionContext” contains all the data changes user makes and more. This can be extracted from “Target” of “InputParameters” :<\/p>\r\n

\r\n\r\n<\/p>\r\n

var isTarget = executionContext.InputParameters.Contains(\"Target\");\r\nvar isTargetTypeEntity = executionContext.InputParameters[\"Target\"] is Entity;\r\n\r\nif (!isTarget || !isTargetTypeEntity) return;\r\n\r\n\/\/ Obtain the target entity from the input parameters.\r\nvar target = (Entity)executionContext.InputParameters[\"Target\"];\r\nvar isTarget = executionContext.InputParameters.Contains(\"Target\");\r\nvar isTargetTypeEntity = executionContext.InputParameters[\"Target\"] is Entity;\r\n\r\nif (!isTarget || !isTargetTypeEntity) return;\r\n\r\n\/\/ Obtain the target entity from the input parameters.\r\nvar target = (Entity)executionContext.InputParameters[\"Target\"];<\/code><\/pre>\r\n
\r\n\r\n<\/p>\r\n
Important to check if the data even exists and its type every time. Records or rows has usually the object “Entity”. We get only raw objects from execution context, therefore we need to cast data every time we use them. The object “Entity” has an “Attributes” property, which is a dictionary with a key-pair values. It contains the field values from our forms. With this information we can get values in code like this:<\/p>\r\n
\r\n\r\n<\/p>\r\n
var accountRef = (EntityReference)target.Attributes[\"parentcustomerid\"];\r\n\r\n\/\/ Getting account with phone number\r\nvar columns = new ColumnSet(\"telephone1\");\r\nvar account = orgService.Retrieve(\"account\", accountRef.Id, columns);\r\n<\/code><\/pre>\r\n
\r\n\r\n<\/p>\r\n
When we reference to another record in Dataverse we can do that with a “Lookup” field which will has a type “EntityReference” in the code. These reference objects store the referenced row ID and logical name.<\/p>\r\n
\r\n\r\n<\/p>\r\n
When we use the object “ColumnSet” we can select which columns we need to reduce the amount of data. This can be crucial for performance. In our example we need only the field “telephone1”. Keep in mind that we need the logical name of columns here.<\/p>\r\n
\r\n\r\n<\/p>\r\n
After retrieving our record we can get the phone number from the Attributes and add it to our contact record. Note: since we plan to run our code in PreOperation stage our changes are still unsaved.<\/p>\r\n
\r\n\r\n<\/p>\r\n
if (account.Attributes[\"telephone1\"] == null) return;\r\n\r\nvar mainPhone = (string)account.Attributes[\"telephone1\"];\r\ntarget.Attributes[\"company\"] = mainPhone;<\/code><\/pre>\r\n
\r\n\r\n<\/p>\r\n
Whole Plugin code<\/h3>\r\n
\r\n\r\n<\/p>\r\n
The whole code together:<\/p>\r\n
\r\n\r\n<\/p>\r\n
using Microsoft.Xrm.Sdk;\r\nusing Microsoft.Xrm.Sdk.Query;\r\nusing System;\r\n\r\nnamespace kogerohu\r\n{\r\n    \/\/\/ <summary>\r\n    \/\/\/ Copy company phone from related Account main phone column if exists when Account is changed.\r\n    \/\/\/ This operation should commit before data will be saved => PreOperation\r\n    \/\/\/ <\/summary>\r\n    public class ContactCopyCompanyPhone : IPlugin\r\n    {\r\n        public void Execute(IServiceProvider serviceProvider)\r\n        {\r\n            IPluginExecutionContext executionContext = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));\r\n\r\n            \/\/ Obtain the Organization Service factory service from the service provider\r\n            IOrganizationServiceFactory factory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));\r\n            IOrganizationService orgService = factory.CreateOrganizationService(executionContext.UserId);\r\n            \r\n            \/\/ The InputParameters collection contains all the data passed in the message request.\r\n            var isTarget = executionContext.InputParameters.Contains(\"Target\");\r\n            var isTargetTypeEntity = executionContext.InputParameters[\"Target\"] is Entity;\r\n\r\n            if (!isTarget || !isTargetTypeEntity) return;\r\n\r\n            \/\/ Obtain the target entity from the input parameters.\r\n            var target = (Entity)executionContext.InputParameters[\"Target\"];\r\n\r\n            \/\/ If there is no related account do nothing\r\n            if (!target.Attributes.ContainsKey(\"parentcustomerid\")) return;\r\n\r\n            var accountRef = (EntityReference)target.Attributes[\"parentcustomerid\"];\r\n\r\n            \/\/ Getting account with phone number\r\n            var columns = new ColumnSet(\"telephone1\");\r\n            var account = orgService.Retrieve(\"account\", accountRef.Id, columns);\r\n\r\n            \/\/ If no main phone, do nothing\r\n            if (account.Attributes[\"telephone1\"] == null) return;\r\n\r\n            var mainPhone = (string)account.Attributes[\"telephone1\"];\r\n\r\n            \/\/ Copy account's main phone to contact's company phone\r\n            target.Attributes[\"company\"] = mainPhone;\r\n\r\n            \/\/ Since target goes further on the execution pipeline\r\n            \/\/ And main stage is next, our data will be saved and\r\n            \/\/ we don't have to save our data manually.\r\n        }\r\n    }\r\n}\r\n<\/code><\/pre>\r\n
\r\n\r\n<\/p>\r\n
To keep the code simple, not all cases had been handled. The VS project can be found on my GitHub page here<\/a>.<\/p>\r\n
\r\n\r\n<\/p>\r\n
Build the Project<\/h3>\r\n
\r\n\r\n<\/p>\r\n
We need to compile our C# code to make it understandable for machines, so we create a DLL file. But to make the upload work properly first we need to sign strongly our project, otherwise we cannot register our assembly.<\/p>\r\n
\r\n\r\n<\/p>\r\n
Sign the Project<\/h4>\r\n
\r\n\r\n<\/p>\r\n
To create a key file with extension”.snk” we need to execute the following in a developer console: “sn -k filename.snk”, which is in my case: “sn -k kogerohu.snk”.<\/p>\r\n
\r\n\r\n<\/p>\r\n
After successful execution go to file explorer in Visual Studio, then right click on the project > select “Properties”.<\/p>\r\n
\r\n\r\n<\/p>\r\n
In the newly opened window select “Signing” in the menu on the left, then scroll down to find checkbox “Sign the assembly”. Find and select your recently created name key file by selecting “Browse” in the drop down.<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Signing<\/figure>\r\n
\r\n\r\n<\/p>\r\n
Do not forget to save your changes (Ctrl + S)!<\/p>\r\n
\r\n\r\n<\/p>\r\n
Build the Project<\/h4>\r\n
\r\n\r\n<\/p>\r\n
We have only a few click left: right click on the project in Solution Explorer and select “Build” command.<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Build\r\n
Building the Project<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
The result of building will be a DLL file under the project under folders “bin\/Debug”. In my case the file is “kogerohu.dll”. (If you cannot see the bin and Debug folders, select “Show All Files” on the ribbon.)<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Debug\r\n
Debug Folder with DLL<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
Register Plugin<\/h2>\r\n
\r\n\r\n<\/p>\r\n
To upload our plugin we will use Plugin Registration Tool.<\/p>\r\n
\r\n\r\n<\/p>\r\n
Download Plugin Registration Tool<\/h3>\r\n
\r\n\r\n<\/p>\r\n
The tool can be downloaded from NuGet. To do that, you can use the following Power Shell script, which downloads all the tools we can use during a project. Execute the script in a Power Shell window:<\/p>\r\n
\r\n\r\n<\/p>\r\n
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12\r\n$sourceNugetExe = \"https:\/\/dist.nuget.org\/win-x86-commandline\/latest\/nuget.exe\"\r\n$targetNugetExe = \".\\nuget.exe\"\r\nRemove-Item .\\Tools -Force -Recurse -ErrorAction Ignore\r\nInvoke-WebRequest $sourceNugetExe -OutFile $targetNugetExe\r\nSet-Alias nuget $targetNugetExe -Scope Global -Verbose\r\n\r\n##\r\n##Download Plugin Registration Tool\r\n##\r\n.\/nuget install Microsoft.CrmSdk.XrmTooling.PluginRegistrationTool -O .\\Tools\r\nmd .\\Tools\\PluginRegistration\r\n$prtFolder = Get-ChildItem .\/Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.XrmTooling.PluginRegistrationTool.'}\r\nmove .\\Tools\\$prtFolder\\tools\\*.* .\\Tools\\PluginRegistration\r\nRemove-Item .\\Tools\\$prtFolder -Force -Recurse\r\n\r\n##\r\n##Download CoreTools\r\n##\r\n.\/nuget install  Microsoft.CrmSdk.CoreTools -O .\\Tools\r\nmd .\\Tools\\CoreTools\r\n$coreToolsFolder = Get-ChildItem .\/Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.CoreTools.'}\r\nmove .\\Tools\\$coreToolsFolder\\content\\bin\\coretools\\*.* .\\Tools\\CoreTools\r\nRemove-Item .\\Tools\\$coreToolsFolder -Force -Recurse\r\n\r\n##\r\n##Download Configuration Migration\r\n##\r\n.\/nuget install  Microsoft.CrmSdk.XrmTooling.ConfigurationMigration.Wpf -O .\\Tools\r\nmd .\\Tools\\ConfigurationMigration\r\n$configMigFolder = Get-ChildItem .\/Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.XrmTooling.ConfigurationMigration.Wpf.'}\r\nmove .\\Tools\\$configMigFolder\\tools\\*.* .\\Tools\\ConfigurationMigration\r\nRemove-Item .\\Tools\\$configMigFolder -Force -Recurse\r\n\r\n##\r\n##Download Package Deployer \r\n##\r\n.\/nuget install  Microsoft.CrmSdk.XrmTooling.PackageDeployment.WPF -O .\\Tools\r\nmd .\\Tools\\PackageDeployment\r\n$pdFolder = Get-ChildItem .\/Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.XrmTooling.PackageDeployment.Wpf.'}\r\nmove .\\Tools\\$pdFolder\\tools\\*.* .\\Tools\\PackageDeployment\r\nRemove-Item .\\Tools\\$pdFolder -Force -Recurse\r\nEzt k\u00f6vet\u0151en megjelenik az Assembly \u00e9s a Plugin a f\u0151 ablak list\u00e1j\u00e1ban\r\n##\r\n##Remove NuGet.exe\r\n##\r\nRemove-Item nuget.exe<\/code><\/pre>\r\n
\r\n\r\n<\/p>\r\n
The tools will be downloaded under folder “..\/Tools\/”, and the Plugin Registration Tool is found under “Plugin Registration” where you can run the “.exe” file.<\/p>\r\n
\r\n\r\n<\/p>\r\n
Work with Plugin Registration Tool<\/h3>\r\n
\r\n\r\n<\/p>\r\n
After opening the program we need to login to our tenant and select the target environment, then we need to get the following main window, select on the top left “Register > Register new Assembly”:<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Plugin\r\n
Plugin Registration Tool<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
Now browse the DLL file, which is under folder “Debug” in our VS project after that leave all the options default.<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Assembly\r\n
Assembly Registration<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
Very important note: if you not check any checkbox in “Step 2”, those plugins will not be registered or will be deleted from the environment if they already exist in the environment!<\/div>\r\n
\r\n\r\n<\/p>\r\n
Click on button “Register Selected Plugins”. In case of successful registration you should get something like this:<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Registration\r\n
Registration Summary<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
Now after clicking “OK” you should see your plugin on the main window.<\/p>\r\n
\r\n\r\n<\/p>\r\n
Create Plugin step<\/h4>\r\n
\r\n\r\n<\/p>\r\n
By a successful registration our assembly and plugin will be uploaded to the Dataverse, but it does nothing so far, because we did not defined after what event and when it should run. To fix this we need to create a so called “plugin step”, so browse and select our new plugin from the list and after a right click on it select “Register New Step”.<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Select\r\n
Select Register new Step<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
A new window pops up, fill it in as follows:<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Plugin\r\n
Register new Step<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
Important to note that I want the plugin to run on event “Update” only for entity “contact” only that case if the field “parentcustomerid” was changed. Do not forget to select the “PreOperation” stage, which helps us to roll back in case of error. If all options are fine, close the window with button “Register New Step”.<\/p>\r\n
\r\n\r\n<\/p>\r\n
If the step registration was successful, it should be appear under our plugin:<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"plugin\r\n
Plugin Step<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
Yeah! From now our plugin will be executed if company will be changed on a contact record.<\/p>\r\n
\r\n\r\n<\/p>\r\n
Adding to a Solution<\/h2>\r\n
\r\n\r\n<\/p>\r\n
I would like to show how you can find our changes on the maker portal and place them in a solution. Visit make.powerapps.com<\/a>, then select your environment on the top right. Create a new or select an existing solution and browse plugin assembly and step as follows:<\/p>\r\n
\r\n\r\n<\/p>\r\n
\"Adding\r\n
Adding Plugin Assembly and Step to the Solution<\/figcaption>\r\n<\/figure>\r\n
\r\n\r\n<\/p>\r\n
When to use plugin<\/h2>\r\n
\r\n\r\n<\/p>\r\n
Instead of using custom code in plugins, you can use workflows to build custom logic as well. Another option is to use Power Automate cloud flows, which is also a no-code low-code tool. Using OOB tools means the customer might not require a programmer for later changes.<\/p>\r\n
\r\n\r\n<\/p>\r\n
Unfortunately all of these tools have their limitations for example in case of Power Automate you logic runs asynchronously which results not having the option to show error message for the user.<\/p>\r\n
\r\n\r\n<\/p>\r\n
As our logic evolves in both tools it can be tool large to have an overview and can be less productive compared to coding.<\/p>\r\n
\r\n\r\n<\/p>\r\n
A few aspects when you might need a plugin in Dataverse:<\/p>\r\n
\r\n\r\n<\/p>\r\n