View Pull Requests in Visual Studio. View all of the Pull Requests for your project in the GitHub pane, and sort and filter them by Open/Closed state, Assignee and Author. Open the GitHub pane by typing GitHub into Visual Studio Quick Launch (Ctrl+Q).-->
Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.
This tutorial is the first in a series that will show you how to work with plug-ins. This tutorial is a pre-requisite for the following tutorials:
For detailed explanation of supporting concepts and technical details see:
Create an asynchronous plug-in registered on the Create message of the account table. The plug-in will create a task activity that will remind the creator of the account to follow up one week later.
This goal can be easily achieved using a workflow without writing code. We are using this simple example so that we can focus on the process of creating and deploying a plug-in.
You need to use Visual Studio to write a plug-in. Use these steps to write a basic plug-in. Alternately, you can find the complete plug-in solution files here: Sample: Create a basic plug-in.
Open Visual Studio and open a new Class Library (.NET Framework) project using .NET Framework 4.6.2
The name used for the project will be the name of the assembly. This tutorial uses the name
In Solution Explorer, right-click the project and select Manage NuGet Packages… from the context menu.
Select Browse and search for
Microsoft.CrmSdk.CoreAssemblies and install the latest version.
You must select I Accept in the License Acceptance dialog.
Microsoft.CrmSdk.CoreAssemblies NuGet package will include these assemblies in the build folder for your assembly, but you will not upload these assemblies with the assembly that includes your logic. These assemblies are already present in the sandbox runtime.
Do not include any other NuGet packages or assemblies to the build folder of your project. You cannot include these assemblies when you register the assembly with your logic. You cannot assume that the assemblies other than those included in the
Microsoft.CrmSdk.CoreAssemblies NuGet package will be present on the server and compatible with your code.
In Solution Explorer, right-click the
Class1.cs file and choose Rename in the context menu.
Class1.cs file to
When prompted, allow Visual Studio to re-name the class to match the file name.
Add the following
using statements to the top of the
Implement the IPlugin interface by editing the class.
If you just type
: IPlugin after the class name, Visual Studio will auto-suggest implementing a stub for the Execute Method.
Replace the contents of the
Execute method with the following code:
The plug-in will create a task activity that will remind the creator of the account to follow up one week later.
Add the following code to the try block. Replace the comment:
// Plug-in business logic goes here. with the following:
regardingobjectidlookup column for the task.
In Visual Studio, press F6 to build the assembly. Verify that it compiles without error.
In Solution Explorer, right click the BasicPlugin project and in the context menu select Properties.
In the project properties, select the Signing tab and select the Sign the assembly checkbox.
In the Choose a strong name key file: dropdown, select <New…>.
In the Create Strong Name Keydialog, enter a key file name and deselect the Protect my key file with a password checkbox.
Click OK to close the Create Strong Name Key dialog.
In the project properties Build tab, verify that the Configuration is set to Debug.
Press F6 to build the plug-in again.
Using windows explorer, find the built plug-in at:
Build the assembly using Debug configuration because you will use the Plug-in Profiler to debug it in a later tutorial. Before you include a plug-in with your solution, you should build it using the release configuration.
To register a plug-in, you will need the Plug-in Registration tool
After you have downloaded the Plug-in registration tool, click the
PluginRegistration.exe to open it.
Click Create new Connection to connect to your instance.
Make sure Office 365 is selected. If you are connecting using a Microsoft account other than one you are currently using, click Show Advanced.
Enter your credentials and click Login.
If your Microsoft Account provides access to multiple environments, you will need to choose an environment.
After you are connected, you will see any existing registered plug-ins & custom workflow activities
In the Register drop-down, select New Assembly.
In the Register New Assembly dialog, select the ellipses (…) button and browse to the assembly you built in the previous step.
For Microsoft 365 users, verify that the isolation mode is set to sandbox and the location to store the assembly is Database.
Other options for isolation mode and location apply to on-premises Dynamics 365 deployments. For the location, you can specify the D365 server's database, the server's local storage (disk), or the server's Global Assembly Cache. For more information see Plug-in storage.
Click Register Selected Plug-ins.
You will see a Registered Plug-ins confirmation dialog.
Click OK to close the dialog and close the Register New Assembly dialog.
You should now see the (Assembly) BasicPlugin assembly which you can expand to view the (Plugin) BasicPlugin.FollowUpPlugin plugin.
Right-click the (Plugin) BasicPlugin.FollowUpPlugin and select Register New Step.
In the Register New Step dialog, set the following fields:
|Event Pipeline Stage of Execution||PostOperation|
Click Register New Step to complete the registration and close the Register New Step dialog.
You can now see the registered step.
At this point the assembly and steps are part of the system Default Solution. When creating a production plug-in, you would add them to the unmanaged solution that you will distribute. These steps are not included in this tutorial. See Add your assembly to a solution and Add step to solution for more information.
Open a model-driven app and create an account table.
Within a short time, open the account and you can verify the creation of the task.
Because this is an asynchronous plug-in, the operation to create the task occurs after the account is created. Usually, this will happen immediately, but if it doesn't you may still be able to view the system job in the queue waiting to be applied. This step registration used the Delete AsyncOperation if StatusCode = Successful option which is a best practice. This means as soon as the system job completes successfully, you will not be able to view the system job data unless you re-register the plug-in with the Delete AsyncOperation if StatusCode = Successful option unselected.
However, if there was an error, you can view the system job to see the error message.
Use the Dynamics 365 --custom app to view system jobs.
In your model-driven app, navigate to the app
In the Dynamics 365 --custom app, navigate to Settings > System > System Jobs.
When viewing system jobs, you can filter by Table (Entity). Select Account.
If the job failed, you should see a record with the name BasicPlugin.FollowupPlugin: Create of account
If you open the system job, you can expand the Details section to view the information written to the trace and details about the error.
You can use the following Web API query to return failed system jobs for asynchronous plug-ins.
More information: Query data using the Web API
Or use the following FetchXml:
More information: Use FetchXML with FetchExpression
The sample code wrote a message to the trace log. The steps below describe how to view the logs.
By default, plug-in trace logs are not enabled.
IF you prefer to change this setting in code:This setting is in the Organization table PluginTraceLogSetting column.
The valid values are:
Use the following steps to enable them in a model-driven app.
Open the Dynamics 365 - custom app.
Navigate to Settings > System > Administration.
In Administration, select System Settings.
In the System Settings dialog, in the customization tab, set Enable logging to plug-in trace log to All.
You should disable logging after you are finished testing your plug-in, or at least set it to Exception rather than All.
Click OK to close the System Settings dialog.
Repeat the steps to test your plug-in by creating a new account.
In the Dynamics 365 -- custom app, navigate to Settings > Customization > Plug-In Trace Log.
You should find that a new plug-in trace Log record has been created.
If you open the record you might expect that it would include the information you set in your trace, but it does not. It only verifies that the trace occurred.
To see the details, it is easier to query this data using the Web API in your browser using the following query with the plugintracelog EntityType, using the
typename property to filter results in the
messageblock property based on the name of the plug-in class:
GET <your org uri>/api/data/v9.0/plugintracelogs?$select=messageblock&$filter=typename eq 'BasicPlugin.FollowUpPlugin'
You can expect to see the following returned with the Web API query:
In this tutorial you have created a simple plug-in and registered it. Complete Tutorial: Debug a plug-in to learn how to debug this plug-in.
Can you tell us about your documentation language preferences? Take a short survey.
The survey will take about seven minutes. No personal data is collected (privacy statement).