Dataverse plug-ins are essential for extending Dynamics 365 functionality, but errors during execution can lead to performance issues, crashes, and unexpected failures. This 10-part blog series will help developers and administrators understand, diagnose, and resolve common Dataverse plug-in errors effectively.

🔹 Blog Series Breakdown:

1️⃣ Time Conversion Errors in Dataverse Plug-ins – Understanding time zone conversion issues and how to prevent them.
2️⃣ Sandbox Worker Process Crashes – Diagnosing and fixing plug-in crashes due to unhandled exceptions, memory limits, and parallel execution issues.
3️⃣ Transaction Errors in Dataverse Plug-ins – Avoiding transaction inconsistencies and handling database commits correctly.
4️⃣ SQL Timeout Errors and Data Operations – Debugging SQL execution timeout errors caused by blocking, cascade operations, and index optimizations.
5️⃣ Memory Leaks and Stack Overflow Errors – Identifying and preventing plug-in memory issues and recursive function failures.
6️⃣ Dataverse Plug-in Execution and Performance Optimization – Optimizing plug-in code for better scalability and reliability.
7️⃣ User Privilege Issues in Plug-ins – Resolving permission-based errors and understanding execution context.
8️⃣ Handling Large Message Payloads in Plug-ins – Managing message size limitations and optimizing data processing.
9️⃣ Dictionary Key Not Found Errors – Preventing and debugging missing key errors in DataCollection<TKey, TValue> objects.
🔟 Activity RegardingObjectId Issues and Lookups – Understanding common lookup field issues in plug-ins and how to fix them.

📌 Blog 1: Time Conversion Errors in Dataverse Plug-ins

Time conversion issues in Dataverse plug-ins can disrupt workflows, cause incorrect timestamps, and break business processes. This blog covers the root cause of the error, troubleshooting steps, and best practices for handling time conversions in plug-ins.

⚠️ Understanding the “Time conversion couldn’t be completed” Error

🔹 Error Code: -2147220956
🔹 Error Message:
“The conversion could not be completed because the supplied DateTime did not have the Kind property set correctly.”

💡 Why Does This Error Occur?

This error occurs when calling TimeZoneInfo.ConvertTimeToUtc(DateTime, TimeZoneInfo) in a Dataverse plug-in while converting DateTime values from specific time zones (e.g., Santiago or Volgograd) to Coordinated Universal Time (UTC).

🔍 Common Causes

✅ The Kind property of DateTime is not properly set.
✅ The source time zone is missing when calling TimeZoneInfo.ConvertTimeToUtc().
✅ The user’s time zone settings are misconfigured in Dataverse.

🔧 Fixing Time Conversion Errors in Plug-ins

✅ Solution 1: Explicitly Set the DateTimeKind Property

One of the most common mistakes is not specifying whether a DateTime is in local time or UTC. Always set DateTimeKind before performing conversions.

DateTime localTime = DateTime.Now;
DateTime utcTime = TimeZoneInfo.ConvertTimeToUtc(
    DateTime.SpecifyKind(localTime, DateTimeKind.Local), 
    TimeZoneInfo.Local);

👉 Why? DateTime.SpecifyKind() explicitly defines whether the time is Local, UTC, or Unspecified, preventing conversion errors.

✅ Solution 2: Use DateTimeOffset Instead of DateTime

Using DateTimeOffset avoids ambiguity and ensures correct UTC conversion.

DateTimeOffset localTime = DateTimeOffset.Now;
DateTime utcTime = localTime.UtcDateTime;

👉 Why? DateTimeOffset includes time zone information, making conversions more reliable.

✅ Solution 3: Verify the User’s Time Zone in Dataverse

If your plug-in depends on the user’s time zone settings, retrieve and validate the user’s time zone ID before performing conversions.

public static TimeZoneInfo GetUserTimeZone(IOrganizationService service, Guid userId)
{
    QueryExpression query = new QueryExpression("usersettings")
    {
        ColumnSet = new ColumnSet("timezonecode"),
        Criteria = new FilterExpression
        {
            Conditions =
            {
                new ConditionExpression("systemuserid", ConditionOperator.Equal, userId)
            }
        }
    };

    EntityCollection results = service.RetrieveMultiple(query);
    if (results.Entities.Count > 0)
    {
        int timeZoneCode = results.Entities[0].GetAttributeValue<int>("timezonecode");
        return TimeZoneInfo.FindSystemTimeZoneById(timeZoneCode.ToString());
    }

    return TimeZoneInfo.Local;
}

👉 Why? This ensures that time conversions align with the user’s Dataverse settings, reducing unexpected errors.

🎯 Key Takeaways

✔️ Time conversion errors occur due to incorrect DateTimeKind settings.
✔️ Using DateTimeOffset instead of DateTime eliminates ambiguity.
✔️ Retrieving user time zone settings from Dataverse ensures accurate conversions.
✔️ Proper exception handling prevents plug-in failures in production.

🔜 Coming Up Next…

In the next one, we will discuss Sandbox Worker Process Crashes, the top reasons plug-ins fail, and how to debug them using Application Insights.