Merge branch 'main' into marcelbf-patch-2

tapanm-MSFT · web-flow · commit 5429455d8d82 · 2024-08-08T15:36:48.000-07:00
diff --git a/powerapps-docs/developer/data-platform/register-plug-in.md b/powerapps-docs/developer/data-platform/register-plug-in.md
@@ -1,7 +1,7 @@
 ---
 title: "Register a plug-in (Microsoft Dataverse) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
 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.
-ms.date: 06/22/2023
+ms.date: 08/06/2024
 ms.reviewer: "pehecke"
 ms.topic: "article"
 author: MicroSri
@@ -18,9 +18,9 @@ contributors:
 
 [!INCLUDE[cc-terminology](includes/cc-terminology.md)]
 
-After a plug-in is written and compiled, it must be registered with the [event framework](event-framework.md) to execute when a specific entity (table row) and message (operation) 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.
+After a plug-in is written and compiled, it must be registered with the [event framework](event-framework.md) to execute when a specific entity (table row) and message (operation) is processed by Microsoft Dataverse. To register a plug-in with Dataverse requires use of a tool - either the Plug-in Registration tool (PRT) or the Power Platform Tools extension for Visual Studio.
 
-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 plug-in related operations using the Plug-in Registration tool.
+The PRT creates Dataverse object registrations and supports editing those registrations. This article describes how to register a plug-in assembly and message processing step, add an assembly to a solution, and perform other common plug-in related operations using the Plug-in Registration tool.
 
 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).
 
@@ -43,7 +43,7 @@ When an assembly is uploaded, it's stored in the `PluginAssembly` table. Most of
 
 ### View registered assemblies
 
-You can view information about registered plug-in assemblies in the Power Apps classic **Solution Explorer**, under **Solutions** in Power Apps left navigation pane, and in the PRT assembly view. To access **Solution Explorer** in Power Apps, choose **Solutions** and then choose **Switch to classic** in the toolbar. To access the default solution from Power Apps, choose **Solutions**, select "Default Solution" in the list, and then choose **Plug-in assemblies** within the left **Objects** pane.
+You can access information about registered plug-in assemblies and steps in Power Apps and in the PRT assembly view. To access plug-in information in Power Apps, choose **Solutions** in the left navigation pane and then choose an available solution from the list. Next, choose **Plug-in assemblies** or **Plug-in steps** within the left **Objects** pane.
 
 > [!NOTE]
 > Each assembly you register will be added to the **Default Solution** which should not be confused with the **Common Data Services Default Solution**.
@@ -56,31 +56,31 @@ As described in [View registered assemblies](#view-registered-assemblies), the a
 To learn more about solutions and how to create one see [Solutions overview](../../maker/data-platform/solutions-overview.md) and [Create a solution](../../maker/data-platform/create-solution.md). Once you have a solution created, you can add your plug-in assembly to it in Power Apps by first choosing the solution in the solution list, and then choose **Add existing** > **More** > **Developer** > **Plug-in assembly**.
 
 > [!NOTE]
-> Any existing or subsequent step registrations (see next section) are not added to the unmanaged solution that includes the plug-in assemblies. You must add each registered step to the solution separately. More information: [Add step to solution](#add-step-to-solution)
+> Any existing or subsequent step registrations (see next section) are not added to the unmanaged solution that includes the plug-in assemblies. You must add each registered step to the solution separately. More information: [Add step to solution](#add-a-step-to-a-solution)
 
 ## Step registration
 
-When an assembly is loaded or updated, any classes that implement <xref:Microsoft.Xrm.Sdk.IPlugin> are made available in the PRT. Use the instructions in [Register a new step](tutorial-write-plug-in.md#register-a-new-step) in the [Tutorial: Write and register a plug-in](tutorial-write-plug-in.md) to create a new step registration.
+Registering a message processing step informs Dataverse under what conditions your plug-in should execute, and how to execute it. By conditions we are referring to the table and message operation being processed by Dataverse. Other configuration options such as synchronous or asynchronous execution, before or after the core operation, and more can be specified during step registration. These runtime configuration options are detailed in the next section.
 
-When you register a step, there are several registration options available to you depending on the stage of the event pipeline and the type of operation you intend to register your code on.
+When an assembly is loaded or updated, any classes that implement <xref:Microsoft.Xrm.Sdk.IPlugin> are made available in the PRT. Use the instructions in [Register a new step](tutorial-write-plug-in.md#register-a-new-step) in the [Tutorial: Write and register a plug-in](tutorial-write-plug-in.md) to create a new step registration.
 
 ### General Configuration Information Fields
 
 |Field|Description|
 |--|--|
-|**Message**|PRT auto-completes available message names in the system. More information: [Use messages with the SDK for .NET](org-service/use-messages.md)|
-|**Primary Entity**|PRT auto-completes valid tables that apply to the selected message. These messages have a `Target` parameter that accepts an <xref:Microsoft.Xrm.Sdk.Entity> or <xref:Microsoft.Xrm.Sdk.EntityReference> type. If valid tables apply, you should set this field value when you want to limit the number of times the plug-in is called. <br />If you leave it blank for core table messages like `Update`, `Delete`, `Retrieve`, and `RetrieveMultiple` or any message that can be applied with the message the plug-in will be invoked for all the tables that support this message.|
+|**Message**|The message that when processed by Dataverse results in plug-in execution.<p/> If a primary entity is not specified for core messages like `Update`, `Delete`, `Retrieve`, and `RetrieveMultiple`, or any message that can be applied, the plug-in will be invoked for all entities that support that message. More information: [Use messages with the SDK for .NET](org-service/use-messages.md)|
+|**Primary Entity**|The entity (table) that when processed by Dataverse results in plug-in execution.<p/> Messages have a `Target` parameter that accepts an <xref:Microsoft.Xrm.Sdk.Entity> or <xref:Microsoft.Xrm.Sdk.EntityReference> type. If valid tables apply, you should set this field value when you want to limit execution of your plug-in to a specific entity being processed.|
 |**Secondary Entity**|This field remains for backward compatibility for deprecated messages that accepted an array of <xref:Microsoft.Xrm.Sdk.EntityReference> as the `Target` parameter. This field is typically not used anymore.|
-|**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. Don't include the primary key of the entity in the filtering attributes. The primary key is always included in update operations, so doing this will negate all other filtered attributes. | 
-|**Event Handler**|This field value will be populated based on the name of the assembly and the plug-in class. |
-|**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.|
+|**Filtering Attributes**|For the `Update`, `OnExternalUpdated`, or other message, when you set the primary entity, filtering attributes (columns) limits the execution of the plug-in to cases where the specified columns are included in the update.<p/>Setting this field is a best practice for performance. Don't include the primary key of the entity in the filtering attributes. The primary key is always included in update operations, so doing this will negate all other filtered attributes. |
+|**Event Handler**|This field value will be populated in the PRT based on the name of the assembly and the plug-in class. |
+|**Step Name**|The name of the message processing step. A value is pre-populated based on the configuration of the step, but this value can be overridden.|
 |**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) |
-|**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.|
-|**Description**|A description for step. This value is pre-populated but can be overwritten.|
+|**Execution Order**|Multiple steps can be registered for the same stage and message. The number in this field determines the order in which the steps are applied within a stage from lowest to highest. You should set this to control the order in which plug-ins are executed in the same stage.<p/>It's not recommended to simply accept the default value. The actual execution order of plug-ins with the same Execution Order value (for the same stage, table and message) isn't guaranteed and can be random.|
+|**Description**|A description for the step. This value is pre-populated but can be overwritten.|
 
 ### Event Pipeline Stage of execution
 
-Choose the stage in the event pipeline that best suites the purpose for your plug-in.
+Choose the stage in the event pipeline that best suites the purpose for your plug-in. The prefix "Pre" and "Post" refers to before or after the Dataverse main (core) operation. The main operation is the stage in which the message and entity combination is processed.
 
 |Option|Description|
 |--|--|
@@ -92,11 +92,11 @@ More information: [Event execution pipeline](event-framework.md#event-execution-
 
 ### Execution Mode
 
-There are two modes of execution asynchronous, and synchronous.
+There are two modes of execution - asynchronous, and synchronous.
 
 |Option|Description|
 |--|--|
-|**Asynchronous**|The execution context and the definition of the business logic to apply is moved to system job, which will execute after the operation completes.|
+|**Asynchronous**|The execution context and the definition of the business logic to apply is moved to the system job queue, which will execute sometime after the main operation completes.|
 |**Synchronous**|Plug-ins execute immediately according to the stage of execution and execution order. The entire operation will wait until they complete.|
 
 Asynchronous plug-ins can only be registered for the **PostOperation** stage. For more information about how system jobs work, see [Asynchronous service](asynchronous-service.md)
@@ -105,7 +105,7 @@ Asynchronous plug-ins can only be registered for the **PostOperation** stage. Fo
 
 There are certain scenarios where a step registration and table combination isn't obvious. This is the result of how the system is designed internally where there's a special relationship between tables or operations. The information below identifies these cases and provides step registration guidance.
 
-- There are certain cases where plug-ins registered for the _Update_ event can be called twice. More information: [Behavior of specialized update operations](special-update-operation-behavior.md)
+- There are certain cases where plug-ins registered for the *Update* event can be called twice. More information: [Behavior of specialized update operations](special-update-operation-behavior.md)
 - Register a plug-in step on **account** or **contact** when you want to handle data changes to **customeraddress**, **leadaddress**, **publisheraddress**, or **competitoraddress** records.
 
 ### Deployment
@@ -154,7 +154,7 @@ In Dataverse, only the following messages support entity images:
 
 #### Types of entity images
 
-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.
+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 main operation and after the main 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.
 
 #### Availability of images
 
@@ -171,7 +171,7 @@ Use the [Power Platform Tools](tools/devtools-install.md) extension for Visual S
 
 Alternately, you can use the Plug-in Registration Tool to add an entity image to a step by following the instructions in [Tutorial: Update a plug-in](tutorial-update-plug-in.md) under the section [Add an image](tutorial-update-plug-in.md#add-an-image).
 
-### Add step to solution
+### Add a step to a solution
 
 As mentioned in [Add your assembly to a solution](#add-your-assembly-to-a-solution), **Plug-in Assemblies** are solution components that can be added to an unmanaged solution. **Sdk Message Processing Steps** are also solution components and must also be added to an unmanaged solution in order to be distributed.
 
@@ -239,6 +239,8 @@ You can also disable or enable steps in the legacy Dataverse Solution Explorer u
 
 :::image type="content" source="media/step-activate-deactivate-commands-solution-explorer.png" alt-text="Changing a plug-in step in legacy Solution Explorer.":::
 
+In Power Apps, disable or enable plug-in steps using the "Turn off" and "Turn on" options of the chosen step. You can access the step options by first navigating to **Solutions**, choosing a solution, and then in the left **Objects** pane choose **Plug-in steps**.
+
 ### Unregister components
 
 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.
diff --git a/powerapps-docs/developer/data-platform/tutorial-write-plug-in.md b/powerapps-docs/developer/data-platform/tutorial-write-plug-in.md
@@ -65,7 +65,7 @@ Another alternative is to use the Power Platform Tools extension as described he
 
     > [!NOTE]
     > Adding the `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.
 
 1. In **Solution Explorer**, right-click the `Class1.cs` file and choose **Rename** in the context menu.
@@ -266,7 +266,7 @@ To register a plug-in, you'll need the Plug-in Registration tool.
     ![View the registered step.](media/tutorial-write-plug-in-view-registered-step.png)
 
 > [!NOTE]
-> 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. For more information, see [Add your assembly to a solution](register-plug-in.md#add-your-assembly-to-a-solution) and [Add step to solution](register-plug-in.md#add-step-to-solution) .
+> 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. For more information, see [Add your assembly to a solution](register-plug-in.md#add-your-assembly-to-a-solution) and [Add step to solution](register-plug-in.md#add-a-step-to-a-solution) .
 
 ## Test plug-in
 
diff --git a/powerapps-docs/developer/data-platform/virtual-entities/get-started-ve.md b/powerapps-docs/developer/data-platform/virtual-entities/get-started-ve.md
