MWTech.Dataverse.PluginToolKit 1.0.0.10

MWTech.Dataverse.PluginToolKit

A comprehensive toolkit for building robust plugins for Microsoft Dataverse (Dynamics 365 CRM). This library provides base classes, helpers, and extensions to simplify plugin development, enforce best practices, and handle common tasks efficiently.

Key Features

Key Features

• Base Classes: UltimatePluginBase and PluginContext for structured plugin development and easy access to all services.
• Helpers: Logging, retry logic, secure config, annotation, metadata, HTTP, bulk operations, entity comparison, exception handling, email, caching, date/time utilities, query building, encryption.
• Extensions: Entity, execution context, fetch XML, plugin stage, service, tracing service.
• Enums: Strongly-typed plugin stage enumeration.
• Error Handling: Centralized logging, retry mechanisms, and optional notifications.
• Performance: Optimized for Dataverse plugin execution.

Folder Structure

• Core/ - Base classes and context encapsulation
• Helpers/ - Utility classes for logging, config, bulk operations, etc.
• Extensions/ - Extension methods for entities, services, and tracing
• Data/Enums/ - Plugin stage enumeration

Getting Started

1. Install the Package

Add the toolkit to your project using NuGet:

dotnet add package MWTech.Dataverse.PluginToolKit

Or use the NuGet Package Manager UI in Visual Studio:

• Search for MWTech.Dataverse.PluginToolKit
• Install the latest version

2. Create Your Plugin

Inherit from UltimatePluginBase and implement your logic:

using MWTech.Dataverse.PluginToolKit.Core;

public class MyPlugin : UltimatePluginBase
{
    protected override void ExecutePluginLogic()
    {
        Logger.LogInfo("Plugin is running!");
        var name = Target?.GetString("name");
        // Your plugin logic here
    }
}

3. Register in Dataverse

• Build your plugin project to generate the DLL.
• Use the Plugin Registration Tool to register your DLL in Dataverse.

Available Properties in UltimatePluginBase

When you inherit from UltimatePluginBase, you get convenient access to commonly used properties:

Core Services

• Service - IOrganizationService instance
• ExecutionContext - IPluginExecutionContext
• TracingService - ITracingService for logging
• Logger - Toolkit Logger instance

Entity Information

• Target - The target entity being processed
• PrimaryEntityName - Name of the primary entity
• PrimaryEntityId - ID of the primary entity
• PrimaryEntityReference - EntityReference for the primary entity
• HasValidPrimaryEntity - Whether the primary entity is valid

Operation Types

• IsCreate - True if this is a Create operation
• IsUpdate - True if this is an Update operation
• IsDelete - True if this is a Delete operation

Execution Context

• MessageName - The message name (Create, Update, Delete, etc.)
• Stage - The plugin execution stage (10, 20, 40, etc.)
• Depth - The execution depth (prevents infinite loops)
• UserId - ID of the user executing the operation
• BusinessUnitId - ID of the user's business unit
• OrganizationId - ID of the organization
• InitiatingUserId - ID of the user who initiated the operation

Images

• PreImage - Pre-operation image (for Update/Delete operations)
• PostImage - Post-operation image (for Update/Create operations)

Stage Checks

• IsPreValidation - True if executing in Pre-Validation stage
• IsPreOperation - True if executing in Pre-Operation stage
• IsMainOperation - True if executing in Main Operation stage
• IsPostOperation - True if executing in Post-Operation stage

Usage Examples

Entity Extensions

Safely access entity attributes:

var name = entity.GetString("name");
var amount = entity.GetDecimal("amount");
var hasField = entity.Has("statuscode");
var lookupId = entity.GetLookupId("parentid");
var changed = entity.HasChanged(preImage, "field");

Execution Context Extensions

Check operation types and get images:

if (Context.IsCreate()) { /* Handle create */ }
if (Context.IsUpdate()) { /* Handle update */ }
var target = Context.GetTargetEntity();
var preImage = Context.GetPreImage();
var postImage = Context.GetPostImage();

Tracing and Logging

Log messages with different levels:

TracingService.LogInfo("Info message");
TracingService.LogError(ex);
Logger.Log("Custom message", LogLevel.Warning);

HTTP Helper

Make HTTP requests:

var result = HttpHelper.Post<MyResponse>(url, payload, headers);
var data = HttpHelper.Get<MyData>(url, headers);

Service Extensions

Perform safe operations:

var account = Service.RetrieveEntity("account", id, columns);
Service.SafeUpdate(entity);
var results = Service.RetrieveMultipleEntities(query);

FetchXml Extensions

Execute FetchXML queries:

var accounts = Service.Fetch<Account>(fetchXml);
var account = Service.FetchSingle<Account>(fetchXml);

Annotation Helpers

Add notes and attachments:

AnnotationHelper.AddSimpleNote(Service, Context.GetPrimaryEntityReference(), "Plugin Ran", "Some useful note.");
AnnotationHelper.AttachAnnotation(Service, new EntityReference("contact", contactId), fileBytes, "file.png", "image/png", "Attachment", "Description");

Bulk Operations

Process multiple entities with chunking and retry:

var result = BulkOperationsHelper.BulkCreate(Service, entities, Logger, chunkSize: 100, maxRetry: 2);
foreach (var id in result.Success) { /* Success */ }
foreach (var failed in result.Failed) { /* Handle failures */ }

Entity Comparison

Compare entities deeply:

var changes = EntityComparisonHelper.GetChangedAttributes(oldEntity, newEntity, ignoreAttributes: new List<string>{"modifiedon"}, deepCompare: true);
if (EntityComparisonHelper.HasChanges(oldEntity, newEntity)) { /* Changes detected */ }

Exception Handling

Handle errors with logging and notifications:

try
{
    // Your logic
}
catch (Exception ex)
{
    ExceptionHelper.Handle(ex, Logger, "Custom error context", notify: true);
    throw;
}

Email Helper

// Send SMTP email
EmailHelper.SendSmtpEmail("smtp.example.com", 587, "from@example.com", "to@example.com", "Subject", "Body");

// Send Dataverse email
var emailId = EmailHelper.SendDataverseEmail(Service, fromParty, toParties, "Subject", "Body", regarding);

Cache Helper

// Set and get cached value
CacheHelper.Set("key", "value", 30); // Expires in 30 minutes
var cached = CacheHelper.Get("key");

DateTime Helper

// Business days
var nextBusinessDay = DateTimeHelper.AddBusinessDays(DateTime.Now, 5);
var businessDays = DateTimeHelper.BusinessDaysBetween(start, end);

QueryBuilder Helper

// Build QueryExpression
var query = QueryBuilderHelper.CreateQuery("account")
    .AddCondition("statecode", ConditionOperator.Equal, 0)
    .AddOrder("name", OrderType.Ascending)
    .SetTopCount(50);

// Build FetchXML
var fetchXml = QueryBuilderHelper.CreateFetchXml("account")
    .AddCondition("statecode", "eq", "0")
    .AddOrder("name", "asc")
    .SetTop(50)
    .ToString();

Encryption Helper

// Encrypt and decrypt data
var encrypted = EncryptionHelper.Encrypt("sensitive data");
var decrypted = EncryptionHelper.Decrypt(encrypted);

// Hash data
var hash = EncryptionHelper.Hash("data to hash");

Best Practices

• Always inherit from UltimatePluginBase for consistency.
• Use helpers and extensions for safe and efficient operations.
• Register your plugin DLL in Dataverse using the Plugin Registration Tool.
• Configure error notifications via environment variables if needed.
• Document new helpers and patterns for your team.

Support

For questions or support, contact Waseem.

Built with ❤️ for real-world CRM developers by MWTech