XrmToolBox Record Compare 2 - Documentation ( IA Generated )

📋 Project Overview

CVN.XrmToolBox.RecordCompare2 is an XrmToolBox plugin designed to compare records between two Dynamics 365/Dataverse environments. It provides detailed insights into differences between source and target organizations, helping identify mismatches, duplications, and missing records.

⭐ Features

Core Capabilities

Record Count Comparison

Quickly identify if source and target have matching record counts

Field-Level Comparison

Compare individual field values across matched records

Bidirectional Analysis

Compare source→target and target→source to catch all discrepancies

Note/Attachment Comparison

Validate notes and attachments are identical

Smart Filtering

Filter by website, creation date, custom expressions, and linked parents

Report Generation

Save comparison results with detailed mismatch files

Supported Models

Standard Model: Uses direct link entities for parent filtering
Enhanced Model: Uses in-memory joins for virtual table support

🔧 Installation & Setup

Prerequisites

XrmToolBox (latest version)
Access to source and target Dynamics 365/Dataverse environments
Administrative permissions in both environments

Installation Steps

Download the plugin DLL: CVN.XRMTOOLBOX.RECORDCOMPARE.dll
Place in XrmToolBox plugins folder: %APPDATA%\Roaming\MscrmTools\XrmToolBox\Plugins
Restart XrmToolBox
Plugin will appear in the Tools menu

Initial Configuration

Open the plugin in XrmToolBox
Configure in Settings:
- Result Folder: Where comparison reports are saved
- XML Configuration: Select or create entity comparison config
- Extension Prefix: Custom prefix for extended fields (e.g., "adx" for Portal)
- Enhanced Model: Enable for virtual tables
- Compare Tool Directory: Path to diff/merge tool
- Dev Env Directory: Path to Visual Studio (optional)

⚙️ Configuration Guide

XML Configuration Structure

The configuration file defines which entities to compare and how:

<?xml version="1.0" encoding="utf-8"?>
<ViewModel>
  <EntityList>
    <CompareEntity>
      <EntityName>mspp_entityformmetadata</EntityName>
      <Name>Entity Form Metadata</Name>
      <NotLinkedToSite>false</NotLinkedToSite>
      <Keys>
        <Key>
          <Name>adx_name</Name>
          <DisplayName>Name</DisplayName>
        </Key>
      </Keys>
    </CompareEntity>
  </EntityList>
</ViewModel>
                    

Configuration Elements

Element	Description
`EntityName`	Logical name of the entity to compare
`Name`	Display name for UI
`NotLinkedToSite`	If false, filters by website ID
`ParentLinkedToSite`	If true, parent records must be in same site
`IntersectEntity`	Set true for intersection/junction entities
`CompareNotes`	If true, compares notes/attachments
`Keys`	Fields used to match records between environments
`LinkedEntityKey`	Foreign key field in linked entity
`LinkedEntityName`	Name of the linked entity
`LinkedFieldName`	Field to retrieve from linked entity

Excluded Fields Configuration

Define fields to skip during comparison (e.g., system fields, timestamps):

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfString>
  <string>createdon</string>
  <string>modifiedon</string>
  <string>createdby</string>
  <string>modifiedby</string>
  <string>versionnumber</string>
</ArrayOfString>
                    

🚀 Usage Guide

Select Target Organization
- Click "Select Target" button
- Choose your target environment connection
- Verify connection details
Select Entities to Compare
- Check the entities you want to compare from the entity list
- Use "Select All" to compare all configured entities
Configure Filters (Optional)
- Website/Site: Select from dropdown
- Created On: Check box and select date to filter by creation date
- Custom filters via XML configuration
Run Comparison
- Click "Run" or "Process" button
- Monitor progress in the status bar
- Wait for comparison to complete
Review Results
- Results appear in the grid showing Type, Entity, Key, Field, V1/V2 values, and Direction
- Large field values are saved to files for comparison
- Use integrated diff tool to visualize changes

📊 Data Models

CompareResult

public class CompareResult
{
    public string EntityName { get; set; }
    public int Count1 { get; set; }           // Source count
    public int Count2 { get; set; }           // Target count
    public bool IsCountOK { get; set; }       // Counts match
    public List<ResultLog> ResultLogs { get; set; }
}
                    

ResultLog

public class ResultLog
{
    public string EntityName { get; set; }
    public string EntityDisplayName { get; set; }
    public ResultLogTypes Type { get; set; }
    public string Key { get; set; }           // Record identifier
    public string Field { get; set; }
    public string V1 { get; set; }            // Source value
    public string V2 { get; set; }            // Target value
    public string Direction { get; set; }     // 1 or 2
    public string V1_Details { get; set; }    // File path for large values
    public string V2_Details { get; set; }
}
                    

Result Types

CountMismatch - Different record counts
NotFound - Record exists in source but not target
Duplication - Multiple matching records in target
Mismatch - Field value differs
NotesCount - Different number of notes
EmptyKey - Key field is null
FilesizeMismatch - Note attachment size differs
NoDifference - No differences found

🎯 Advanced Features

Linked Entity Matching

Match records by related entity fields (e.g., match by Form Name instead of ID):

<Key>
  <Name>mspp_entityformid</Name>
  <LinkedEntityKey>mspp_entityformid</LinkedEntityKey>
  <LinkedEntityName>mspp_entityform</LinkedEntityName>
  <LinkedFieldName>adx_name</LinkedFieldName>
</Key>
                    

Parent Record Filtering

Filter child records by parent's website:

<ParentLinkedToSite>true</ParentLinkedToSite>
<ParentTableName>mspp_website</ParentTableName>
<ParentKeyName>mspp_websiteid</ParentKeyName>
<LinkKeyName>mspp_websiteid</LinkKeyName>
                    

File Comparison

Large field values (>40 characters) are automatically saved to files:

JSON files: Auto-formatted for readability
HTML files: Detected and formatted
XML files: Detected and preserved
Text files: Plain text comparison

🐛 Troubleshooting

Issue: "No results found" or empty comparison

Solutions:

Verify website selection is correct
Check if date filter is excluding records
Ensure entities are configured in XML
Verify entity permissions in both environments

Issue: Service connection fails

Solutions:

Test connection with basic retrieve query
Check network connectivity
Verify authentication credentials
Review debug output window

Issue: Virtual table comparison shows different counts

Solutions:

Enable "Enhanced Model" in settings
Ensure ParentLinkedToSite is configured correctly
Check parent records exist in target environment

Issue: Notes comparison fails

Solutions:

Verify CompareNotes is enabled in config
Check annotation records have filenames
Ensure file paths are accessible

📁 Output & Reports

Result Files

Comparison results are saved to the configured Result Folder:

Large field values saved with format-specific extensions (.json, .xml, .html, etc.)
File naming: {RecordId}_{Step}_{Service}.{ext}
Example: 550e8400_1_1.json

Viewing Results

In-Application: Browse grid in plugin
File System: Open Result Folder
Diff Tool: Right-click → Open with configured comparison tool

⚡ Performance Considerations

Large Datasets

Tool loads results in-memory for filtering
Recommended limit: 5,000 records per entity
For larger sets: Use date filters or custom filters

Optimization Tips

Filter by creation date to reduce scope
Use specific keys for matching (avoid generic fields)
Exclude unnecessary fields
Disable note comparison if not needed
Run during off-peak hours

📚 Configuration Examples

Example 1: Portal Entities (Standard Model)

<CompareEntity>
  <EntityName>adx_webpage</EntityName>
  <Name>Web Pages</Name>
  <NotLinkedToSite>false</NotLinkedToSite>
  <Keys>
    <Key>
      <Name>adx_name</Name>
      <DisplayName>Name</DisplayName>
    </Key>
  </Keys>
</CompareEntity>
                    

Example 2: Linked Records with Parent Filter

<CompareEntity>
  <EntityName>adx_webform</EntityName>
  <Name>Web Forms</Name>
  <ParentLinkedToSite>true</ParentLinkedToSite>
  <ParentTableName>adx_website</ParentTableName>
  <Keys>
    <Key>
      <Name>adx_name</Name>
      <DisplayName>Name</DisplayName>
    </Key>
  </Keys>
</CompareEntity>
                    