Writing and deploying a sample plugin with Dynamics 365/Power Apps

 

Let's say we want to write a plugin for the logic that we previously implemented using JavaScript, where we auto-populated the Email field in an account entity record from a selected contact. Let's use the following steps to write our plugin:

1. Navigate to Visual Studio | New and select Class Library (.NET Framework).

While creating the solution, keep in mind that we can use .NET Framework version 4.6.2 or later for Dynamics 365 CE.

2. Once the project has been created, we can rename the class based on our requirements; for example, we have renamed it SetEmailFrmContactOnAccountPreCreate.
3. Let's add Dynamics 365 CE assemblies to our project. Right-click on our project and select the Manage NuGet Packages option.
4. Add some Dynamics 365 CE assemblies, as shown in the following screenshot. You need to follow the numbered steps indicated in the following screenshot to do this:

5. Accept the license prompt. This will add all the required assemblies to our project.
6. We need to add the following two namespace references to our class:

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;

The Microsoft.Xrm.Sdk namespace is the core namespace for working with Dynamics 365 CE entities. This namespace also has an IPlugin interface, which we need to implement to write a plugin. The Microsoft.Xrm.Sdk.Query namespace contains classes that we will be using to query Dynamics 365 CE data.

7. After that, we need to inherit the IPlugin interface and implement its Execute method. We can do this by following the numbered steps shown in the following screenshot:

The Execute method is the entry function for our plugin logic. Our custom logic starts executing from this method. It can be considered the main method. This method takes a single parameter of the IServiceProvider type, which has a GetService method that we will be using to get a different service object.

8. Next, we need to add the following line, which will help us get the service object:

IPluginExecutionContext pluginContext = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

We use the preceding line to get the plugin context from the serviceProvider parameter that we get in the Execute method of the plugin. It helps us get contextual information about the environment that our plugin is executing in. Using pluginContext, we can get different properties, such as business units and parameter collection.

You can see a full list of properties at https://docs.microsoft.com/en-us/dotnet/api/microsoft.xrm.sdk.ipluginexecutioncontext?view=dynamics-general-ce-9.

While working with the plugin, we can handle exceptions and create tracing logs. All the tracing-related methods are available in the ITracingService class:

ITracingService tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));

9. Next, we need to use the following two lines to get the IOrganization service object. The IOrganizationservice provides us with different methods that we can use to work with entity data and metadata:

IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService orgService = serviceFactory.CreateOrganizationService(pluginContext.UserId);

In the preceding code, we are creating an Organization service object using pluginContext.UserId, which means it will use the user that's been configured in the plugin registration tool in the Run in User's Context field. By default, calling the user is configured in this field, which means it will create an Organization service object based on the initiating user.

10. Next, we need to get an entity from the input parameters. The input parameters are a collection of parameters that we can get from the plugin context that we collected earlier. What parameter we get in the input parameter collection depends on the plugin event that we used to register our plugin. For example, in the case of the Create message, we will always get a Target parameter. We can get it and validate whether it is an entity class type as follows:

if (pluginContext.InputParameters.Contains("Target") && pluginContext.InputParameters["Target"] is Entity)

11. Once we have checked the Target parameter, we can get the entity and look for the fields that we want to validate. In our case, we want to check whether the user filled in Primary Contact in the account form or not. If Primary Contact is available, we can fetch it and query the contact entity based on the primary contact, as follows:

try {
 Entity account = (Entity) pluginContext.InputParameters["Target"];
if (account.LogicalName != "account") {
 return;
 }
 if (account.Contains("primarycontactid")) {
 Entity contact = orgService.Retrieve("contact", account.GetAttributeValue < EntityReference > ("primarycontactid").Id, new ColumnSet(new string[] {
 "emailaddress1"
 }));
 if (contact.Contains("emailaddress1"))
 account.Attributes.Add("emailaddress1", contact.GetAttributeValue < string > ("emailaddress1"));
 }}
 catch (FaultException < OrganizationServiceFault > ex) {
 tracingService.Trace(ex.Message + " : " + ex.StackTrace);
 throw ex;
} catch (Exception e) {
 tracingService.Trace(e.Message + " : " + e.StackTrace);
 throw e;
}
}

In the preceding code, after fetching the primary contact entity, we added the emailaddress1 field under the account entity attributes collection. We are going to register our plugin on PreCreate so that it will pass the emailaddress1 field in the account object with input parameter collection and be saved with the main database operation:

account.Attributes.Add("emailaddress1", contact.GetAttributeValue<string>("emailaddress1"));

12. If we want to change an entity after it has been created, we need to use the Update method specifically. We also need to handle the exception in our code. As you can see, we have written our code under a try-catch block. After catching the exception, we can add an exception under the trace log for better troubleshooting.
13. Now, we need to sign our assembly to provide a strong name. Right-click on the project and select Properties. This will open some property windows where we can select the signing option to give our assembly a strong key name, as follows:

Once you've built your project to generate an assembly file, you can register the plugin.

 

 

Navigate to the plugin registration tool folder and open PluginRegistration.exe. We need to take the following steps to register a plugin:

1. Click on the CREATE NEW CONNECTION button to open a connection window. Fill in your Dynamics 365 CE credentials after selecting your data region; for example, for me, this is India.
2. Click on Login to be connected to your Dynamics 365 CE default organization. If you have multiple organizations, you can also check the Display list of available organizations checkbox while entering credentials. This will show you a list of organizations that are accessible to you.
3. Click on the Register dropdown and select Register New Assembly.
4. Browse your assembly file and keep all the options in the dialog as their defaults.

When registering the plugin, we need to specify the isolation mode. In the case of Dynamics 365 CE Online, we need to select Sandbox. None is selected when we are working with on-premise organizations. We can register our assembly in three locations:

• DataBase: This is the best option as you can register your assembly where the assembly is stored in the organization database. If required, we can also retrieve our assembly using code. This option is available for both Dynamics 365 CE Online and on-premise versions.
• Disk: When using this option, our assembly is stored in our hard disk location. This option was used in the early versions of Dynamics CRM for better debugging support and is only available for on-premise deployments.
• GAC: When using this option, our assembly is stored in the global assembly cache. This option is only available for on-premise deployment.

With these options, we should always deploy our assembly to the database because it is secure and assembly code can be retrieved from the database if we lose it.

5. Click on the Register Selected Plugins button.

Keep in mind that your plugin class should be public; otherwise, you won't be able to see any plugin details after browsing your project assembly while registering the plugin.

6. Look for your assembly in the assembly list and expand it to see all the available plugins. Right-click on the plugin and select Register New Step.

When registering the plugin, we need to specify the following details:

• Message: Here, we specify the event that we want to register our plugin on; for example, Create, Update, or Delete.
• Primary Entity: Here, we provide the logical name of the entity that we want to register our plugin on.
• Secondary Entity: Some events require two entities; for example, the SetRelated event. So, here, we specify the second entity.
• Filtering Attributes: This option is used for update events where we can specify the entity attribute. If we do this, our plugin will only execute when these attributes are updated.
• Event Handler: This provides details about the plugin assembly. We don't need to change anything here.

• Step Name: This provides details about the plugin step. This is automatically filled.
• Run in User's Context: By default, Calling User is selected here. If we want to run our plugin using a specific user, we can specify that user here.
• Execution Order: If multiple plugins are registered on the same event, we can specify the execution order of our plugins here.
• Description: Description of the plugin.
• Event Pipeline Stage of Execution: We can select options such as PreValidation, PreOperation, and PostOperation from here, which we discussed in detail in the Implementing custom logic using plugins section.
• Execution Mode: Here, we specify whether we want to run our plugin in synchronous or asynchronous mode.
• Deployment: Here, we specify that our plugin should be available to the server only or whether we want to run our logic in offline mode as well; for example, when Outlook is running in offline mode.
• Delete AsyncOperation if StatusCode=Successful: We can use this option to save disk space. It will delete all completed async operation records.
• Unsecure Configuration: Here, we specify unsecured configuration data for our plugin, which can be read by any user. These settings are transferred to another organization within the solution.
• Secure Configuration: These configurations can only be read by the system administrator and are not transferred to another environment within the solution.

We need to use the following details for our plugin:

• Message: Create
• Primary Entity: Account
• Event Pipeline Stage of Execution: PreOperation

Keep all the details as their default.

Make sure that you disable the OnChange event for the primary contact field where we associated our JavaScript function on the account entity form. Now, when we create an account and fill in the primary contact ID, it will auto-populate with the email from the contact entity when we hit Save. Our logic will run before the save operation.

Similarly, we can write plugins for other events. Now that we know how we can register our custom logic in Dynamics 365 CE using plugins, let's learn how to debug our Dynamics 365 CE Online plugins.