Xrm.Json.Serialization 1.2026.3.1

Xrm.Json.Serialization

Compact JSON serialization library for Microsoft Dynamics 365/CRM/Dataverse entities using Newtonsoft.Json.

Features

• ✅ Compact JSON format optimized for Dynamics 365 entities
• ✅ Complete data type support for all major CRM SDK types including AliasedValue
• ✅ Custom converters for CRM-specific types (EntityReference, OptionSetValue, Money, etc.)
• ✅ Bidirectional serialization and deserialization
• ✅ Easy integration with existing Dynamics 365 SDK projects
• ✅ Built for .NET Framework 4.6.2 - Plugin compatible!
• ✅ FetchXML support - Properly handles linked entities with AliasedValue
• ✅ Helper class - EntitySerializer for simplified usage

Supported Data Types

This library provides custom JSON converters for the following Dynamics 365 data types:

Installation

NuGet Package Manager

Install-Package Xrm.Json.Serialization

.NET CLI

dotnet add package Xrm.Json.Serialization

Package Reference

<PackageReference Include="Xrm.Json.Serialization" Version="1.2026.3.0" />

Usage

Basic Serialization

using Xrm.Json.Serialization;
using Microsoft.Xrm.Sdk;
using Newtonsoft.Json;

// Create a Dynamics 365 entity
var account = new Entity("account", Guid.NewGuid());
account["name"] = "Contoso Ltd";
account["revenue"] = new Money(1000000m);
account["industrycode"] = new OptionSetValue(1);
account["parentaccountid"] = new EntityReference("account", Guid.NewGuid());
account["createdon"] = DateTime.UtcNow;

// Configure JSON serializer with XRM contract resolver
var settings = new JsonSerializerSettings
{
    ContractResolver = new XrmContractResolver(),
    Formatting = Formatting.Indented
};

// Serialize to JSON
string json = JsonConvert.SerializeObject(account, settings);
Console.WriteLine(json);

Deserialization

using Xrm.Json.Serialization;
using Microsoft.Xrm.Sdk;
using Newtonsoft.Json;

string json = @"{
    ""_reference"": ""account:12345678-1234-1234-1234-123456789012"",
    ""name"": ""Contoso Ltd"",
    ""revenue"": {
        ""_money"": 1000000
    },
    ""industrycode"": {
        ""_option"": 1
    }
}";

var settings = new JsonSerializerSettings
{
    ContractResolver = new XrmContractResolver()
};

// Deserialize from JSON
var account = JsonConvert.DeserializeObject<Entity>(json, settings);
Console.WriteLine($"Account: {account["name"]}");
Console.WriteLine($"Revenue: {((Money)account["revenue"]).Value}");

Entity Collection Serialization

using Xrm.Json.Serialization;
using Microsoft.Xrm.Sdk;
using Newtonsoft.Json;

var collection = new EntityCollection();

collection.Entities.Add(new Entity("account", Guid.NewGuid())
{
    ["name"] = "Account 1"
});

collection.Entities.Add(new Entity("account", Guid.NewGuid())
{
    ["name"] = "Account 2"
});

var settings = new JsonSerializerSettings
{
    ContractResolver = new XrmContractResolver(),
    Formatting = Formatting.Indented
};

string json = JsonConvert.SerializeObject(collection, settings);

Individual Converter Usage

You can also use individual converters directly:

// Entity Reference
var reference = new EntityReference("contact", Guid.NewGuid());
var json = JsonConvert.SerializeObject(reference, new EntityReferenceConverter());

// Money
var money = new Money(50000m);
var json = JsonConvert.SerializeObject(money, new MoneyConverter());

// OptionSet
var optionSet = new OptionSetValue(100000001);
var json = JsonConvert.SerializeObject(optionSet, new OptionSetConverter());

Helper Class for Easy Serialization

For simplified usage, especially in plugins:

using Xrm.Json.Serialization;
using Microsoft.Xrm.Sdk;

// Serialize
var entity = new Entity("account", Guid.NewGuid());
entity["name"] = "Contoso";

string json = EntitySerializer.Serialize(entity);
string indentedJson = EntitySerializer.Serialize(entity, indented: true);

// Deserialize
var deserializedEntity = EntitySerializer.DeserializeEntity(json);

Plugin Usage

This library is compatible with Dynamics 365 plugins (targets .NET Framework 4.6.2), but requires special deployment considerations:

⚠️ Plugin Deployment Requirements

Since Dynamics 365 plugins run in an isolated sandbox, you have two options for deployment:

Option 1: ILMerge (Traditional)

Merge this library and Newtonsoft.Json into your plugin assembly:

<ItemGroup>
  <PackageReference Include="ILMerge" Version="3.0.41" />
  <PackageReference Include="Xrm.Json.Serialization" Version="1.1.0" />
</ItemGroup>

Build script:

ILMerge.exe /out:MyPlugin.Merged.dll MyPlugin.dll Xrm.Json.Serialization.dll Newtonsoft.Json.dll /targetplatform:v4,C:\Windows\Microsoft.NET\Framework64\v4.0.30319

Option 2: NuGet Plugin Package (Modern - Recommended)

Use the Power Platform build tools to create a plugin package with dependencies:

<ItemGroup>
  <PackageReference Include="Microsoft.PowerPlatform.Dataverse.Client" Version="1.1.14" />
  <PackageReference Include="Xrm.Json.Serialization" Version="1.1.0" />
</ItemGroup>

<PropertyGroup>
  <PowerAppsTargetsPath>$(MSBuildExtensionsPath)\Microsoft\PowerApps-Targets</PowerAppsTargetsPath>
  <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
</PropertyGroup>

This creates a .nupkg file that bundles all dependencies for deployment to Dynamics 365 Online.

Note: For on-premises deployments, you can register assemblies individually, but online requires one of the above approaches.

Logging and Diagnostics

public class MyPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

        // Log entity snapshot for debugging
        var preImage = context.PreEntityImages["PreImage"];
        var json = EntitySerializer.Serialize(preImage, indented: true);
        tracingService.Trace($"Pre-Image:\n{json}");
    }
}

Azure Service Bus Integration

public class SendToServiceBusPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var entity = (Entity)context.InputParameters["Target"];

        // Serialize and send to Azure Service Bus
        var json = EntitySerializer.Serialize(entity);
        var message = new ServiceBusMessage(json);

        // Send to your service bus (async pattern)
        await serviceBusClient.SendMessageAsync(message);
    }
}

Webhook Notifications

public class WebhookPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var entity = (Entity)context.InputParameters["Target"];

        // Send entity data to external webhook
        var json = EntitySerializer.Serialize(entity);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        using (var client = new HttpClient())
        {
            var response = client.PostAsync("https://your-webhook.com/api/updates", content).Result;
        }
    }
}

FetchXML with Linked Entities

AliasedValue support is critical for FetchXML queries with linked entities:

public class FetchXmlPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
        var service = serviceFactory.CreateOrganizationService(context.UserId);

        var fetchXml = @"
            <fetch>
              <entity name='account'>
                <attribute name='name' />
                <link-entity name='contact' from='contactid' to='primarycontactid' alias='contact'>
                  <attribute name='fullname' />
                  <attribute name='emailaddress1' />
                </link-entity>
              </entity>
            </fetch>";

        var results = service.RetrieveMultiple(new FetchExpression(fetchXml));

        // Serialize results including aliased values from linked entities
        var json = EntitySerializer.Serialize(results, indented: true);

        // Process each entity with aliased values
        foreach (var entity in results.Entities)
        {
            if (entity.Contains("contact.fullname"))
            {
                var aliasedValue = (AliasedValue)entity["contact.fullname"];
                var contactName = aliasedValue.Value.ToString();
            }
        }
    }
}

Redis Caching in Plugins

public class CachePlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var entityId = context.PrimaryEntityId;

        // Cache entity in Redis
        var cacheKey = $"account:{entityId}";
        var entity = /* retrieve entity */;
        var json = EntitySerializer.Serialize(entity);

        cache.SetString(cacheKey, json, TimeSpan.FromMinutes(15));

        // Later retrieve from cache
        var cachedJson = cache.GetString(cacheKey);
        if (cachedJson != null)
        {
            var cachedEntity = EntitySerializer.DeserializeEntity(cachedJson);
        }
    }
}

External Integration Usage

For external applications (console apps, web APIs, Azure Functions), no special deployment is needed - just reference the NuGet package:

Console Application Example

using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Tooling.Connector;
using Xrm.Json.Serialization;

class Program
{
    static void Main(string[] args)
    {
        // Connect to Dynamics 365
        var connectionString = "AuthType=OAuth;...";
        var service = new CrmServiceClient(connectionString);

        // Retrieve and serialize
        var account = service.Retrieve("account", accountId, new ColumnSet(true));
        var json = EntitySerializer.Serialize(account, indented: true);

        Console.WriteLine(json);

        // Save to file, send to API, cache, etc.
        File.WriteAllText("account.json", json);
    }
}

Azure Functions Example

[FunctionName("ProcessDynamicsData")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req,
    ILogger log)
{
    // Deserialize from request
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    var entity = EntitySerializer.DeserializeEntity(requestBody);

    log.LogInformation($"Processing entity: {entity.LogicalName}");

    // Process and return
    var response = new 
    { 
        success = true,
        entityName = entity.LogicalName
    };

    return new OkObjectResult(response);
}

Web API Example

[ApiController]
[Route("api/[controller]")]
public class DynamicsController : ControllerBase
{
    private readonly IOrganizationService _service;

    [HttpGet("account/{id}")]
    public IActionResult GetAccount(Guid id)
    {
        var account = _service.Retrieve("account", id, new ColumnSet(true));
        var json = EntitySerializer.Serialize(account);

        return Content(json, "application/json");
    }

    [HttpPost("account")]
    public IActionResult CreateAccount([FromBody] string json)
    {
        var account = EntitySerializer.DeserializeEntity(json);
        var id = _service.Create(account);

        return Ok(new { id });
    }
}

Compact JSON Format

The library produces compact, optimized JSON representations for Dynamics 365 data types:

Entity Reference

{
  "_reference": "account:12345678-1234-1234-1234-123456789012"
}

Money

{
  "_money": 1000000
}

OptionSetValue

{
  "_option": 1
}

OptionSetValueCollection (Multi-Select Picklist)

{
  "_options": [1, 2, 3]
}

AliasedValue (FetchXML Linked Entities)

{
  "_aliased": "contact|fullname|John Doe"
}

BooleanManagedProperty

{
  "_boolmanaged": "True|False"
}

Guid

{
  "_id": "12345678-1234-1234-1234-123456789012"
}

Complete Entity Example

{
  "_reference": "account:12345678-1234-1234-1234-123456789012",
  "name": "Contoso Ltd",
  "revenue": {
    "_money": 1000000
  },
  "industrycode": {
    "_option": 1
  },
  "parentaccountid": {
    "_reference": "account:87654321-4321-4321-4321-210987654321"
  },
  "createdon": "2024-01-15T10:30:00Z",
  "contact.fullname": {
    "_aliased": "contact|fullname|John Doe"
  }
}

Requirements

• .NET Framework 4.6.2 or higher (Plugin compatible! ✅)
• Microsoft.CrmSdk.CoreAssemblies (>= 9.0.2.60)
• Newtonsoft.Json (>= 13.0.3)

Note: This library targets .NET Framework 4.6.2, making it fully compatible with Dynamics 365 plugins which run on .NET Framework 4.6.2 runtime.

Use Cases

This library is ideal for:

• Plugin development - Logging, diagnostics, and external integrations in Dynamics 365 plugins
• FetchXML queries - Serialize results with linked entities (AliasedValue support)
• API integrations - Transmit Dynamics 365 data via REST APIs
• Data export/import - Backup and restore entity data
• Caching - Store entity data in Redis, file systems, or other caches
• Logging - Serialize entities for audit trails and debugging
• Message queues - Send entity data through Azure Service Bus, RabbitMQ, etc.
• Webhooks - Push Dynamics 365 changes to external systems
• Multi-select picklists - Handle OptionSetValueCollection fields

Why Compact Format?

Traditional Dynamics 365 entity serialization can be verbose. This library provides:

• Smaller payload sizes - Reduced network bandwidth and storage
• Faster serialization - Optimized for performance
• Easier debugging - Human-readable JSON structure
• Type safety - Preserves CRM data type information

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

• Alexey Shytikov - Original author
• Imran Akram - Maintainer

Links

• GitHub Repository
• NuGet Package
• Issues

Changelog

Version 1.2026.3.0 (March 2026)

• ✅ NEW: AliasedValue converter for FetchXML linked entity support
• ✅ NEW: OptionSetValueCollection converter for multi-select picklists
• ✅ NEW: BooleanManagedProperty converter
• ✅ NEW: EntitySerializer helper class for simplified usage
• ✅ FIX: String escaping issue with double quotes and special characters (#20)
• ✅ TARGET: .NET Framework 4.6.2 (plugin compatible)
• ✅ DOCS: Added comprehensive plugin usage examples
• ✅ TESTS: Added 27 new tests for new converters

Version 1.2022.10.1 (October 2022)

• Namespace change from Innofactor.Xrm.Json.Serialization to Xrm.Json.Serialization
• Package metadata updates

Version 1.0.0 (2021)

• Initial release
• Support for all major Dynamics 365 data types
• Entity, EntityReference, EntityCollection converters
• OptionSetValue, Money, DateTime, Guid converters
• XrmContractResolver for seamless integration
• Comprehensive test coverage