You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: powerapps-docs/developer/data-platform/register-plug-in.md
+44-93Lines changed: 44 additions & 93 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: "Register a plug-in (Microsoft Dataverse) | Microsoft Docs"# Intent and product brand in a unique string of 43-59 chars including spaces
3
-
description: "Learn how to register a plug-in in a step of the Microsoft Dataverse event pipeline."# 115-145 characters including spaces. This abstract displays in the search result.
4
-
ms.date: 04/07/2023
3
+
description: "Learn how to register a plug-in assembly and step with the Microsoft Dataverse event framework pipeline."# 115-145 characters including spaces. This abstract displays in the search result.
4
+
ms.date: 06/22/2023
5
5
ms.reviewer: "pehecke"
6
6
ms.topic: "article"
7
7
author: "divkamath"# GitHub ID
@@ -10,45 +10,29 @@ ms.author: "jdaly" # MSFT alias of Microsoft employees only
You can use Power Platform Tools for Visual Studio to quickly create and deploy (register) plug-ins. A [quickstart](tools/devtools-create-plugin.md) article is available to show you how.
21
+
After a plug-in is written and compiled, it must be registered with the event framework to execute when a specific entity type (table) and operation (message) is processed by Dataverse. To register a plug-in with the Dataverse event framework requires use of a tool - Plug-in Registration tool (PRT), or the Power Platform Tools extension for Visual Studio.
22
22
23
-
A more manual process of writing, registering, and debugging a plug-in is:
23
+
The PRT creates Dataverse object registrations and supports editing those registrations. This article describes how to register a plug-in assembly and step, add an assembly to a solution, and perform other common operations using the Plug-in Registration tool.
24
24
25
-
1. Create a .NET Framework class library project in Visual Studio
26
-
1. Add the `Microsoft.CrmSdk.CoreAssemblies` NuGet package to the project
27
-
1. Implement the <xref:Microsoft.Xrm.Sdk.IPlugin> interface on classes to be registered on plug-in steps.
28
-
1. Add your code to the <xref:Microsoft.Xrm.Sdk.IPlugin.Execute*> method required by the interface
29
-
1. Get references to services you need
30
-
1. Add your custom business logic
31
-
1. Sign & build the assembly
32
-
1. Test the assembly
33
-
1. Register the assembly in a test environment
34
-
1. Add your registered assembly and steps to an unmanaged solution
35
-
1. Test the behavior of the assembly
36
-
1. Verify expected trace logs are written
37
-
1. Debug the assembly as needed
25
+
The Visual Studio extension provides a more feature rich development environment and covers the entire coding, deployment, and debugging/profiling development process. For information about using the Power Platform Tools extension for Visual Studio, see the [quickstart](tools/devtools-create-plugin.md).
38
26
39
-
This topic describes how to register a plug-in assembly and step, and add them to a solution. Additional information can be found in these tutorials:
27
+
More information: [Event framework](event-framework.md)
40
28
41
-
-[Tutorial: Write and register a plug-in](tutorial-write-plug-in.md)
42
-
-[Tutorial: Debug a plug-in](tutorial-debug-plug-in.md)
43
-
-[Tutorial: Update a plug-in](tutorial-update-plug-in.md)
29
+
## About the Plug-in Registration tool
44
30
45
-
##Plug-in Registration tool (PRT)
31
+
The Plug-in Registration tool (PRT) supports registration of plug-in assemblies, message processing steps, and other types of objects with Dataverse. PRT is one of several Dataverse tools available for download from [NuGet.org](https://www.nuget.org). Follow the instructions in [Dataverse development tools](download-tools-nuget.md) to download PRT and optionally other development tools.
46
32
47
-
You use the Plug-in Registration tool (PRT) to register your plug-in assemblies and steps.
33
+
After you download the PRT, follow the [Connect using the Plug-in Registration tool](tutorial-write-plug-in.md#register-plug-in) instructions to connect the tool to your target Dataverse environment where your plug-in is to be registered.
48
34
49
-
PRT is one of the tools available for download from NuGet. Follow the instructions in [Dataverse development tools](download-tools-nuget.md). That topic includes Power Platform CLI instructions to download PRT and other development tools from NuGet.
50
-
51
-
After you download the PRT, use the [Connect using the Plug-in Registration tool](tutorial-write-plug-in.md#connect-using-the-plug-in-registration-tool) steps in the [Tutorial: Write and register a plug-in](tutorial-write-plug-in.md) to connect to your Microsoft Dataverse environment.
35
+
:::image type="content" source="media/dv_plugin_registration_tool.png" alt-text="The Plug-in Registration tool main window.":::
52
36
53
37
## Register an assembly
54
38
@@ -76,55 +60,6 @@ After selecting the name of the Default Solution in the internal solution list,
76
60
77
61
78
62
79
-
### Query registered assemblies with code
80
-
81
-
To view information about registered assemblies without the PRT or the application, use the following Web API query in your browser:
82
-
83
-
```
84
-
[org uri]]/api/data/v9.0/pluginassemblies
85
-
?$filter=ishidden/Value eq false
86
-
&$select=
87
-
createdon,
88
-
culture,
89
-
customizationlevel,
90
-
description,
91
-
isolationmode,
92
-
major,
93
-
minor,
94
-
modifiedon,
95
-
name,
96
-
pluginassemblyid,
97
-
publickeytoken,
98
-
version
99
-
```
100
-
101
-
Or use following FetchXml to retrieve it in a program you write:
More information: [Use FetchXML with FetchExpression](org-service/entity-operations-query-data.md#use-fetchxml-with-fetchexpression)
127
-
128
63
## Add your assembly to a solution
129
64
130
65
As described in [View registered assemblies](#view-registered-assemblies), the assembly registration you created was added to the system **Default Solution**. You should add your assembly to an unmanaged solution so you can distribute it to other organizations.
@@ -160,7 +95,7 @@ When you register a step, there are several registration options available to yo
160
95
|**Filtering Attributes**|With the `Update` or `OnExternalUpdated` message, when you set the **Primary Entity**, filtering columns limits the execution of the plug-in to cases where the selected columns are included in the update. Setting this field is a best practice for performance. |
161
96
|**Event Handler**|This field value will be populated based on the name of the assembly and the plug-in class. |
162
97
|**Step Name**|The name of the step. A value is pre-populated based on the configuration of the step, but this value can be overridden.|
163
-
|**Run in User's Context**|Provides options for applying impersonation for the step. The default value is **Calling User**. If the calling user doesn't have privileges to perform operations in the step, you may need to set this field value to a user who has these privileges. More information: [Impersonate a user](impersonate-a-user.md)|
98
+
|**Run in User's Context**|Provides options for applying impersonation for the step. The default value is **Calling User**. If the calling user doesn't have privileges to perform operations in the step, you may need to set this field value to a user who has these privileges. More information: [Set user impersonation for a step](#set-user-impersonation-for-a-step)|
164
99
|**Execution Order**|Multiple steps can be registered for the same stage of the same message. The number in this field determines the order in which they'll be applied from lowest to highest. <br/> **Note**: You should set this to control the order in which plug-ins are applied in the stage. It's not recommended to simply accept the default value. The actual execution order of the plugins with the same Execution Order value (for the same stage, table and message) isn't guaranteed and can be random.|
165
100
|**Description**|A description for step. This value is pre-populated but can be overwritten.|
166
101
@@ -238,7 +173,6 @@ In Dataverse, only the following messages support entity images:
238
173
|`SetState`|`EntityMoniker`|The table for which the state is set.|
239
174
|`Update`|`Target`|The updated table.|
240
175
241
-
242
176
#### Types of entity images
243
177
244
178
There are two types of entity images: **Pre Image** and **Post Image**. When you configure them, these images will be available within the execution context as <xref:Microsoft.Xrm.Sdk.IExecutionContext.PreEntityImages> and <xref:Microsoft.Xrm.Sdk.IExecutionContext.PostEntityImages> properties respectively. As the names suggest, these snapshots represent what the table looks like before the operation and after the operation. When you configure an entity image, you'll define a table alias* value that will be the key value you'll use to access a specific entity image from the `PreEntityImages` or `PostEntityImages` properties.
@@ -252,7 +186,6 @@ When you configure an entity image, it's important that you recognize that the t
252
186
- You can only have a **Post Image** for steps registered in the **PostOperation** stage of the execution pipeline because there's no way to know what the table properties will be until the transaction is completed.
253
187
- For an `Update` operation that is registered in the **PostOperation** stage you can have both a **Pre Image** AND a **Post Image**.
254
188
255
-
256
189
#### Add an entity image
257
190
258
191
Use the [Power Platform Tools](tools/devtools-install.md) extension for Visual Studio to [add an entity image](tools/devtools-create-plugin.md#add-an-entity-image) to a plug-in step.
@@ -271,6 +204,19 @@ If you encounter this, you should usually select **OK** to bring the assembly in
271
204
272
205
Similarly, you should note that removing the assembly from the solution won't remove any steps that depend on it.
273
206
207
+
### Set user impersonation for a step
208
+
209
+
With the Plug-in Registration tool running and logged into the target Dataverse environment, you can proceed to set or change a step registration. In this section, we will discuss changing the user on whos behalf the plug-in will perform its operations. Meaning, the effective user that is performing the data operations initiated by the plug-in. By default, the calling user (the user that invoked an operation in Dataverse) is the owner of said operations. However a different user can be specified in the step registration. You will need to have the System Administrator or System Customizer security role to perform this operation.
210
+
211
+
To set the user in a plug-in step:
212
+
213
+
1. Expand the target plug-in assembly node in the assembly view until you see the desired (Step) registration node.
214
+
1. Choose the step node, and then choose **Update** in either the context menu or the toolbar.
215
+
1. Choose a different user from the drop-down list of available users next to the **Run in User's Context** label.
216
+
1. Choose **Update Step**.
217
+
218
+
More information: [Impersonate a user](impersonate-a-user.md)
219
+
274
220
## Update an assembly
275
221
276
222
When you change and rebuild an assembly that you've previously registered, you'll need to update it. See the [Update the plug-in assembly registration](tutorial-update-plug-in.md#update-the-plug-in-assembly-registration) step in the [Tutorial: Update a plug-in](tutorial-update-plug-in.md) for the steps.
@@ -289,14 +235,31 @@ Plug-in assemblies can be versioned using a semantic versioning format of `major
289
235
290
236
When an updated solution containing the revised assembly is imported, the assembly is considered a different assembly than the previous version of that assembly in the existing solution. Plug-in registration steps in the existing solution will continue to refer to the previous version of the assembly. If you want existing plug-in registration steps for the previous assembly to point to the revised assembly, you'll need to use the Plug-in Registration tool to manually change the step configuration to refer to the revised assembly type. This should be done before exporting the updated assembly into a solution for later import.
291
237
292
-
293
238
## Unregister or disable plug-ins and components
294
239
295
240
You can unregister or disable plug-ins and their components using the Plug-in Registration tool (PRT).
296
241
297
242
> [!IMPORTANT]
298
243
> It is no longer possible to unregister or disable Microsoft or out-of-box system plug-ins and steps. Previously, you were able to unregister or disable some of the Microsoft.* and other out-of-box system plug-ins. We have changed this behavior to no longer allow this. The change in functionality was made because unregistering or disabling these plug-ins or steps can cause product features not to work as expected. If you have a need to unregister or disable such a plug-in or step, file a Microsoft support request.
299
244
245
+
### Disable or enable a plug-in step
246
+
247
+
With the Plug-in Registration tool running and logged into the target Dataverse environment, you can proceed to disable or enable plug-in steps. Disabling a step effectively turns off the plug-in from executing when Dataverse processes the entity and message combination specified in the step registration.
248
+
249
+
> [!IMPORTANT]
250
+
> Disabling a plug-in can negatively affect the functionality of your app, a solution, or the Dataverse system. Make sure you understand the implications before you proceed.
251
+
252
+
To disable or enable a registered plug-in step:
253
+
254
+
1. Expand the target plug-in assembly node in the assembly view until you see the desired step registration node.
255
+
1. Choose the step, and then choose **Enable** or **Disable** in either the context menu or the toolbar.
256
+
257
+
:::image type="content" source="media/disable-step-prt.png" alt-text="Disable a step using the Plug-in Registration tool.":::
258
+
259
+
You can also disable or enable steps in the legacy Dataverse Solution Explorer user interface using the **Activate** and **Deactivate** command options.
260
+
261
+
:::image type="content" source="media/step-activate-deactivate-commands-solution-explorer.png" alt-text="Changing a plug-in step in legacy Solution Explorer.":::
262
+
300
263
### Unregister components
301
264
302
265
The PRT provides commands to unregister assemblies, types, steps, and images. See the [Unregister assembly, plug-in, and step](tutorial-update-plug-in.md#unregister-assembly-plug-in-and-step) instructions in the [Tutorial: Update a plug-in](tutorial-update-plug-in.md) for the procedure.
@@ -310,28 +273,16 @@ You can also delete **Plug-in Assemblies** and **Sdk Message Processing Steps**
310
273
> [!NOTE]
311
274
> You cannot delete (unregister) any **Plug-in Assemblies** while existing **Sdk Message Processing Steps** depend on them. Entity images are not available to be deleted separately, but they will be deleted when any steps that use them are deleted.
312
275
313
-
### Disable steps
314
-
315
-
The PRT provides commands to disable and enable steps.
316
-
317
-
318
-
319
-
320
-
321
-
You can also disable steps in the solution explorer using the **Activate** and **Deactivate** commands.
0 commit comments