Understanding the Primary Entity in the Plugin Registration Tool: A Comprehensive Guide

In Microsoft Dynamics 365 and Dataverse, the Primary Entity in the Plugin Registration Tool defines the main table (entity) that the plugin targets and determines when it will execute in response to a specific system event, known as a message. Each plugin step must specify a message such as Create, Update, Delete, or Retrieve, and the primary entity identifies which record type that message applies to—such as account, contact, or incident. For instance, if a plugin is registered with the message “Update” and the primary entity “account,” it will trigger whenever an Account record is updated. The primary entity provides the context for the plugin execution, allowing developers to access the target record and perform business logic accordingly. In some cases, such as with the Associate or Disassociate messages, the primary entity may be left blank since the operation involves a relationship between multiple entities. Understanding the role of the primary entity is crucial for correctly configuring plugin steps, ensuring precise execution, and maintaining reliable business automation across Dynamics 365 solutions.

Role in the Execution Context

When a Dataverse message (e.g., Create, Update, Delete, Assign) is invoked against a record, the platform constructs an execution context (IPluginExecutionContext) that includes metadata about the operation.

One key property within this context is:

context.PrimaryEntityName

This value corresponds exactly to the Primary Entity specified during registration. It tells the plugin which entity type the event originated from, enabling the developer to write logic that handles the operation appropriately.

Example:

if (context.PrimaryEntityName.Equals("account", StringComparison.OrdinalIgnoreCase))

{

    // Logic specific to Account entity

}

Relationship with the Message (Event)

The Primary Entity and the Message Name work together to define when and where the plugin fires:

If you register a plugin with:

Message: Update

Primary Entity: account

Stage: PostOperation

 The Dataverse pipeline invokes your plugin after an Account record is successfully updated.

Input and Output Parameters Depend on Primary Entity

The Primary Entity also affects the structure of the context.InputParameters and context.OutputParameters.

For example:

• When Message = Create, InputParameters["Target"] contains the new entity record of type Primary Entity.
• When Message = Update, InputParameters["Target"] contains only the updated columns of that Primary Entity.
• When Message = Retrieve, OutputParameters["BusinessEntity"] returns the retrieved Primary Entity.

Example:

if (context.MessageName == "Update" && context.InputParameters.Contains("Target"))

{

    Entity target = (Entity)context.InputParameters["Target"];

    if (target.LogicalName == context.PrimaryEntityName)

    {

        // Operate on the specific entity record

    }

}

Technical Constraints and Best Practices

• The Primary Entity must be valid and exist in the Dataverse schema (logical name like account, contact, incident, etc.).
• For custom entities, use the logical name (e.g., new_projectentity).
• If the message is global (e.g., Associate, RetrieveMultiple), the Primary Entity may be left blank (none).
• You can register the same plugin assembly multiple times for different primary entities if your logic applies across entities.
• Always check context.PrimaryEntityName inside your plugin to avoid unintended execution from multiple steps.

Behind the Scenes

When you register a plugin step, Dataverse creates a record in the sdkmessageprocessingstep table.

The key fields include:

• sdkmessageid → Links to the message (e.g., Update)
• primaryobjecttypecode → Corresponds to the entity metadata ID of the Primary Entity
• eventhandler → References your plugin class

When a transaction occurs (e.g., an update on the Account table), the Dataverse runtime filters all registered steps based on:

1. The message ID
2. The primary object type code
3. The execution pipeline stage

Only matching steps are executed.

In the Plugin Registration Tool for Microsoft Dataverse, the Primary Entity defines the main table (entity) that triggers the plugin’s execution. When you register a plugin step, selecting a Primary Entity ensures that the plugin only runs for specific operations (like Create, Update, Delete, etc.) performed on that entity.

For example, if you register a plugin on the Account entity with the Update message, it will trigger whenever an account record is updated. The Primary Entity acts as the central context of the operation and provides the data accessible through the plugin’s context.InputParameters and context.OutputParameters.

The Primary Entity also determines where in the Dataverse event pipeline (PreValidation → PreOperation → Platform Operation → PostOperation) the plugin executes. This allows developers to perform validations, modify data before saving, or take post-save actions tied directly to that entity.

In short, the Primary Entity anchors the plugin to a specific business operation in Dataverse, ensuring that custom logic runs precisely when and where it’s intended.