using Polly;
using Polly.Extensions.Http;

namespace DataverseEventTranslator.Infrastructure.Resilience
{
    public class ResilienceService
    {
        private readonly IAsyncPolicy _retryPolicy;
        private readonly IAsyncPolicy _circuitBreakerPolicy;
        private readonly ILogger<ResilienceService> _logger;

        public ResilienceService(ILogger<ResilienceService> logger)
        {
            _logger = logger;

            // Retry policy with exponential backoff
            _retryPolicy = Policy
                .Handle<HttpRequestException>()
                .Or<TaskCanceledException>()
                .Or<TimeoutException>()
                .WaitAndRetryAsync(
                    retryCount: 3,
                    sleepDurationProvider: retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
                    onRetry: (outcome, timespan, retryCount, context) =>
                    {
                        _logger.LogWarning("Retry attempt {RetryCount} after {Delay}ms for operation {OperationKey}",
                            retryCount, timespan.TotalMilliseconds, context.OperationKey);
                    });

            // Circuit breaker pattern
            _circuitBreakerPolicy = Policy
                .Handle<Exception>()
                .CircuitBreakerAsync(
                    handledEventsAllowedBeforeBreaking: 5,
                    durationOfBreak: TimeSpan.FromMinutes(1),
                    onBreak: (exception, duration) =>
                    {
                        _logger.LogError(exception, "Circuit breaker opened for {Duration}ms", duration.TotalMilliseconds);
                    },
                    onReset: () =>
                    {
                        _logger.LogInformation("Circuit breaker reset");
                    });
        }

        public async Task<T> ExecuteWithRetryAsync<T>(
            Func<Task<T>> operation,
            string operationName,
            CancellationToken cancellationToken = default)
        {
            var context = new Context(operationName);
            return await _retryPolicy.ExecuteAsync(async (ctx) =>
            {
                try
                {
                    return await operation();
                }
                catch (Exception ex) when (IsRetriableException(ex))
                {
                    _logger.LogWarning(ex, "Retriable error in operation {OperationName}", operationName);
                    throw;
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Non-retriable error in operation {OperationName}", operationName);
                    throw;
                }
            }, context);
        }

        public async Task ExecuteWithCircuitBreakerAsync(
            Func<Task> operation,
            string operationName,
            CancellationToken cancellationToken = default)
        {
            try
            {
                await _circuitBreakerPolicy.ExecuteAsync(operation);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Circuit breaker protected operation {OperationName} failed", operationName);
                throw;
            }
        }

        private bool IsRetriableException(Exception ex)
        {
            return ex is HttpRequestException ||
                   ex is TaskCanceledException ||
                   ex is TimeoutException ||
                   (ex.Message?.Contains("throttle", StringComparison.OrdinalIgnoreCase) == true);
        }
    }
}

namespace DataverseEventTranslator.Infrastructure.DeadLetter
{
    public interface IDeadLetterService
    {
        Task SendAsync(object message, Exception exception, string correlationId);
        Task<IEnumerable<DeadLetterMessage>> GetMessagesAsync(int count = 10);
        Task ReprocessMessageAsync(string messageId);
    }

    public class ServiceBusDeadLetterService : IDeadLetterService
    {
        private readonly ServiceBusClient _serviceBusClient;
        private readonly ILogger<ServiceBusDeadLetterService> _logger;
        private readonly string _deadLetterQueueName;

        public ServiceBusDeadLetterService(
            ServiceBusClient serviceBusClient,
            IConfiguration configuration,
            ILogger<ServiceBusDeadLetterService> logger)
        {
            _serviceBusClient = serviceBusClient;
            _logger = logger;
            _deadLetterQueueName = configuration.GetValue<string>("DeadLetterQueue:Name") ?? "dead-letter-queue";
        }

        public async Task SendAsync(object message, Exception exception, string correlationId)
        {
            try
            {
                var sender = _serviceBusClient.CreateSender(_deadLetterQueueName);

                var deadLetterMessage = new DeadLetterMessage
                {
                    Id = Guid.NewGuid().ToString(),
                    OriginalMessage = JsonConvert.SerializeObject(message),
                    Exception = exception.ToString(),
                    CorrelationId = correlationId,
                    FailedAt = DateTime.UtcNow,
                    RetryCount = 0,
                    MaxRetries = 3
                };

                var serviceBusMessage = new ServiceBusMessage(JsonConvert.SerializeObject(deadLetterMessage))
                {
                    MessageId = deadLetterMessage.Id,
                    CorrelationId = correlationId,
                    ContentType = "application/json"
                };

                await sender.SendMessageAsync(serviceBusMessage);

                _logger.LogInformation("Message sent to dead letter queue. MessageId: {MessageId}, CorrelationId: {CorrelationId}",
                    deadLetterMessage.Id, correlationId);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to send message to dead letter queue. CorrelationId: {CorrelationId}", correlationId);
                throw;
            }
        }

        public async Task<IEnumerable<DeadLetterMessage>> GetMessagesAsync(int count = 10)
        {
            var receiver = _serviceBusClient.CreateReceiver(_deadLetterQueueName);
            var messages = await receiver.ReceiveMessagesAsync(count, TimeSpan.FromSeconds(10));

            return messages.Select(msg => JsonConvert.DeserializeObject<DeadLetterMessage>(msg.Body.ToString()));
        }

        public async Task ReprocessMessageAsync(string messageI# Translating Dataverse CRUD Events to Business Events

## Overview

This guide demonstrates how to transform generic Dataverse CRUD (Create, Read, Update, Delete) events into meaningful business events using Azure Event Hub and C#. Instead of consuming low-level database operations, downstream systems receive semantically rich events that represent actual business processes.

## Understanding Dataverse Event Publishing

### How Dataverse Publishes Events

Dataverse (formerly Common Data Service) has a sophisticated event publishing system built on the concept of **Service Endpoints**. Understanding this mechanism is crucial for implementing effective event translation.

#### The Plugin Framework Foundation

Dataverse operates on a plugin-based architecture where custom code can be executed in response to data operations. The system provides several execution contexts:

- **Pre-Operation**: Before the database transaction
- **Post-Operation**: After the database transaction but within the same transaction
- **Asynchronous**: After the transaction completes, executed separately

#### Service Endpoints: The Event Publishing Mechanism

Service Endpoints are specialized plugins that instead of executing custom logic locally, forward event data to external systems. They act as bridges between Dataverse's internal event system and external messaging platforms.

**Key Components:**

1. **Plugin Registration Tool**: Administrative interface for configuring what events trigger which endpoints
2. **Event Execution Pipeline**: Dataverse's internal event processing system
3. **Service Endpoint Configuration**: Defines where and how events are sent
4. **Pre/Post Images**: Snapshots of entity data before and after operations

**Event Flow Within Dataverse:**

```mermaid
graph TD
    A[User Action] --> B[Dataverse Core]
    B --> C[Event Pipeline]
    C --> D{Plugin Steps}
    D --> E[Pre-Operation Plugins]
    D --> F[Database Operation]
    D --> G[Post-Operation Plugins]
    D --> H[Service Endpoints]
    H --> I[External System<br/>Azure Event Hub]

    E --> J[Pre-Images Generated]
    G --> K[Post-Images Generated]
    J --> H
    K --> H

{
  "EntityType": "contact",
  "Operation": "Update",
  "EntityId": "12345678-1234-1234-1234-123456789012",
  "ModifiedFields": ["emailaddress1", "modifiedon"],
  "Timestamp": "2024-07-11T15:30:00Z"
}

{
  "EventType": "ContactUpdated",
  "ContactId": "12345678-1234-1234-1234-123456789012",
  "FullName": "John Doe",
  "ChangedFields": ["emailaddress1"],
  "PreValues": {
    "emailaddress1": "john.old@company.com"
  },
  "PostValues": {
    "emailaddress1": "john.new@company.com"
  },
  "ChangedAt": "2024-07-11T15:30:00Z",
  "ChangedBy": "admin@company.com"
}

{
  "EventType": "ContactEmailChanged",
  "ContactId": "12345678-1234-1234-1234-123456789012",
  "FullName": "John Doe",
  "OldEmailAddress": "john.old@company.com",
  "NewEmailAddress": "john.new@company.com",
  "ChangedAt": "2024-07-11T15:30:00Z",
  "ChangedBy": "admin@company.com",
  "RequiresEmailVerification": true
}

// Generic event for view projections
public class ContactUpdated : BusinessEvent
{
    public ContactUpdated() { EventType = "ContactUpdated"; }

    public string ContactId { get; set; }
    public string FullName { get; set; }
    public string[] ChangedFields { get; set; }
    public Dictionary<string, object> PreValues { get; set; }
    public Dictionary<string, object> PostValues { get; set; }
    public string ChangedBy { get; set; }
}

// Specific business event for email changes
public class ContactEmailChanged : BusinessEvent
{
    public ContactEmailChanged() { EventType = "ContactEmailChanged"; }

    public string ContactId { get; set; }
    public string FullName { get; set; }
    public string OldEmailAddress { get; set; }
    public string NewEmailAddress { get; set; }
    public string ChangedBy { get; set; }
    public bool RequiresEmailVerification { get; set; }
    public string AccountId { get; set; } // Parent customer if available
}

// Other specific business events
public class ContactPhoneChanged : BusinessEvent
{
    public ContactPhoneChanged() { EventType = "ContactPhoneChanged"; }

    public string ContactId { get; set; }
    public string FullName { get; set; }
    public string PhoneType { get; set; } // "Business" or "Mobile"
    public string OldPhoneNumber { get; set; }
    public string NewPhoneNumber { get; set; }
    public string ChangedBy { get; set; }
}

public class ContactStatusChanged : BusinessEvent
{
    public ContactStatusChanged() { EventType = "ContactStatusChanged"; }

    public string ContactId { get; set; }
    public string FullName { get; set; }
    public string OldStatus { get; set; }
    public string NewStatus { get; set; }
    public string StatusChangeReason { get; set; }
    public string ChangedBy { get; set; }
}

public async Task<List<BusinessEvent>> MapContactEventsAsync(
    DataverseExecutionContext context, 
    CancellationToken cancellationToken)
{
    var events = new List<BusinessEvent>();
    var preImage = context.PreEntityImages["PreImage"];
    var postImage = context.PostEntityImages["PostImage"];
    var contactId = context.PrimaryEntityId.ToString();

    // Always generate a generic ContactUpdated event for view projections
    var genericEvent = await CreateGenericContactUpdatedEvent(preImage, postImage, contactId, context);
    if (genericEvent != null)
    {
        events.Add(genericEvent);
    }

    // Generate specific business events based on field changes
    await AddEmailChangeEventIfNeeded(preImage, postImage, contactId, events, context);
    await AddPhoneChangeEventsIfNeeded(preImage, postImage, contactId, events, context);
    await AddStatusChangeEventIfNeeded(preImage, postImage, contactId, events, context);

    return events;
}

private async Task<ContactUpdated> CreateGenericContactUpdatedEvent(
    DataverseEntity preImage, 
    DataverseEntity postImage, 
    string contactId,
    DataverseExecutionContext context)
{
    var changedFields = DetectChangedFields(preImage, postImage);

    if (!changedFields.Any())
        return null; // No relevant changes

    var preValues = new Dictionary<string, object>();
    var postValues = new Dictionary<string, object>();

    foreach (var field in changedFields)
    {
        preValues[field] = preImage.GetAttributeValue<object>(field);
        postValues[field] = postImage.GetAttributeValue<object>(field);
    }

    return new ContactUpdated
    {
        ContactId = contactId,
        FullName = postImage.GetAttributeValue<string>("fullname"),
        ChangedFields = changedFields.ToArray(),
        PreValues = preValues,
        PostValues = postValues,
        ChangedBy = context.InitiatingUser?.Email
    };
}

private async Task AddEmailChangeEventIfNeeded(
    DataverseEntity preImage, 
    DataverseEntity postImage, 
    string contactId,
    List<BusinessEvent> events,
    DataverseExecutionContext context)
{
    var oldEmail = preImage.GetAttributeValue<string>("emailaddress1");
    var newEmail = postImage.GetAttributeValue<string>("emailaddress1");

    if (oldEmail != newEmail && !string.IsNullOrEmpty(newEmail))
    {
        // Get parent account for context
        var parentCustomerId = postImage.GetAttributeValue<Guid?>("parentcustomerid");

        events.Add(new ContactEmailChanged
        {
            ContactId = contactId,
            FullName = postImage.GetAttributeValue<string>("fullname"),
            OldEmailAddress = oldEmail,
            NewEmailAddress = newEmail,
            ChangedBy = context.InitiatingUser?.Email,
            RequiresEmailVerification = ShouldRequireEmailVerification(oldEmail, newEmail),
            AccountId = parentCustomerId?.ToString()
        });

        _logger.LogInformation("Contact email changed: {ContactId} from {OldEmail} to {NewEmail}",
            contactId, oldEmail, newEmail);
    }
}

private bool ShouldRequireEmailVerification(string oldEmail, string newEmail)
{
    // Business logic: require verification if this is a new email or domain change
    if (string.IsNullOrEmpty(oldEmail))
        return true; // New email address

    var oldDomain = oldEmail.Split('@').LastOrDefault();
    var newDomain = newEmail.Split('@').LastOrDefault();

    return oldDomain != newDomain; // Domain changed
}

private List<string> DetectChangedFields(DataverseEntity preImage, DataverseEntity postImage)
{
    var changedFields = new List<string>();
    var relevantFields = new[] 
    { 
        "firstname", "lastname", "emailaddress1", "telephone1", 
        "mobilephone", "jobtitle", "statuscode", "parentcustomerid" 
    };

    foreach (var field in relevantFields)
    {
        var preValue = preImage.GetAttributeValue<object>(field);
        var postValue = postImage.GetAttributeValue<object>(field);

        if (!object.Equals(preValue, postValue))
        {
            changedFields.Add(field);
        }
    }

    return changedFields;
}

// Consumer that updates materialized views based on ContactUpdated events
public class ContactViewProjectionConsumer
{
    public async Task HandleContactUpdatedAsync(ContactUpdated contactEvent)
    {
        // Update search index
        await _searchService.UpdateContactAsync(contactEvent.ContactId, contactEvent.PostValues);

        // Update reporting database
        await _reportingService.ProjectContactChangesAsync(contactEvent);

        // Update cache
        await _cacheService.InvalidateContactAsync(contactEvent.ContactId);

        _logger.LogInformation("Projected contact changes for {ContactId} with fields: {Fields}",
            contactEvent.ContactId, string.Join(", ", contactEvent.ChangedFields));
    }
}

// Consumer that handles email change business logic
public class ContactEmailChangeConsumer
{
    public async Task HandleContactEmailChangedAsync(ContactEmailChanged emailEvent)
    {
        if (emailEvent.RequiresEmailVerification)
        {
            // Send email verification
            await _emailService.SendVerificationEmailAsync(emailEvent.NewEmailAddress, emailEvent.ContactId);

            // Create verification record
            await _verificationService.CreateVerificationRecordAsync(emailEvent.ContactId, emailEvent.NewEmailAddress);

            _logger.LogInformation("Email verification sent for contact {ContactId} to {NewEmail}",
                emailEvent.ContactId, emailEvent.NewEmailAddress);
        }

        // Update email marketing lists
        await _marketingService.UpdateContactEmailAsync(emailEvent.ContactId, emailEvent.NewEmailAddress);

        // Notify related systems
        if (!string.IsNullOrEmpty(emailEvent.AccountId))
        {
            await _notificationService.NotifyAccountOfContactEmailChangeAsync(emailEvent.AccountId, emailEvent);
        }
    }
}

{
  "MessageName": "Update",
  "TimeStamp": "2024-07-11T15:30:00Z",
  "ExecutionContext": {
    "PrimaryEntityName": "contact",
    "PrimaryEntityId": "12345678-1234-1234-1234-123456789012",
    "PreEntityImages": {
      "PreImage": {
        "Id": "12345678-1234-1234-1234-123456789012",
        "LogicalName": "contact",
        "Attributes": {
          "fullname": "John Doe",
          "emailaddress1": "john.old@company.com",
          "telephone1": "555-0123",
          "jobtitle": "Developer",
          "statuscode": { "Value": 1 }
        }
      }
    },
    "PostEntityImages": {
      "PostImage": {
        "Id": "12345678-1234-1234-1234-123456789012",
        "LogicalName": "contact",
        "Attributes": {
          "fullname": "John Doe",
          "emailaddress1": "john.new@company.com",
          "telephone1": "555-0123",
          "jobtitle": "Senior Developer",
          "statuscode": { "Value": 1 }
        }
      }
    },
    "InitiatingUser": {
      "UserId": "87654321-4321-4321-4321-210987654321",
      "Email": "admin@company.com",
      "FullName": "System Administrator"
    }
  }
}

{
  "EventId": "11111111-1111-1111-1111-111111111111",
  "EventType": "ContactUpdated",
  "ContactId": "12345678-1234-1234-1234-123456789012",
  "FullName": "John Doe",
  "ChangedFields": ["emailaddress1", "jobtitle"],
  "PreValues": {
    "emailaddress1": "john.old@company.com",
    "jobtitle": "Developer"
  },
  "PostValues": {
    "emailaddress1": "john.new@company.com",
    "jobtitle": "Senior Developer"
  },
  "ChangedBy": "admin@company.com",
  "OccurredAt": "2024-07-11T15:30:00Z",
  "SourceSystem": "Dataverse",
  "EventVersion": "1.0",
  "CorrelationId": "22222222-2222-2222-2222-222222222222"
}

{
  "EventId": "33333333-3333-3333-3333-333333333333",
  "EventType": "ContactEmailChanged",
  "ContactId": "12345678-1234-1234-1234-123456789012",
  "FullName": "John Doe",
  "OldEmailAddress": "john.old@company.com",
  "NewEmailAddress": "john.new@company.com",
  "ChangedBy": "admin@company.com",
  "RequiresEmailVerification": true,
  "AccountId": null,
  "OccurredAt": "2024-07-11T15:30:00Z",
  "SourceSystem": "Dataverse",
  "EventVersion": "1.0",
  "CorrelationId": "22222222-2222-2222-2222-222222222222"
}

private bool ShouldProcessContactUpdate(DataverseExecutionContext context)
{
    var preImage = context.PreEntityImages["PreImage"];
    var postImage = context.PostEntityImages["PostImage"];

    // Filter out system-only updates (like modifiedon, modifiedby)
    var businessRelevantFields = new[] 
    { 
        "firstname", "lastname", "emailaddress1", "telephone1", 
        "mobilephone", "jobtitle", "statuscode", "parentcustomerid" 
    };

    return businessRelevantFields.Any(field => 
        !object.Equals(preImage.GetAttributeValue<object>(field), 
                      postImage.GetAttributeValue<object>(field)));
}

private async Task EnrichContactEventAsync(ContactUpdated contactEvent, DataverseEntity postImage)
{
    // Add computed fields
    contactEvent.Metadata.Add("HasEmailAddress", !string.IsNullOrEmpty(postImage.GetAttributeValue<string>("emailaddress1")));
    contactEvent.Metadata.Add("HasPhoneNumber", 
        !string.IsNullOrEmpty(postImage.GetAttributeValue<string>("telephone1")) || 
        !string.IsNullOrEmpty(postImage.GetAttributeValue<string>("mobilephone")));

    // Add relationship context
    var parentCustomerId = postImage.GetAttributeValue<Guid?>("parentcustomerid");
    if (parentCustomerId.HasValue)
    {
        contactEvent.Metadata.Add("ParentAccountId", parentCustomerId.ToString());
        // Could fetch additional account details if needed
    }

    // Add change categorization
    contactEvent.Metadata.Add("ChangeCategory", CategorizeChanges(contactEvent.ChangedFields));
}

private string CategorizeChanges(string[] changedFields)
{
    if (changedFields.Contains("emailaddress1")) return "ContactInformation";
    if (changedFields.Contains("telephone1") || changedFields.Contains("mobilephone")) return "ContactInformation";
    if (changedFields.Contains("jobtitle")) return "ProfessionalInformation";
    if (changedFields.Contains("statuscode")) return "StatusChange";
    return "GeneralUpdate";
}

private async Task ProcessEventBatchAsync(IEnumerable<PartitionEvent> events, CancellationToken cancellationToken)
{
    var businessEvents = new List<BusinessEvent>();

    foreach (var partitionEvent in events)
    {
        try
        {
            var dataverseEvent = ParseDataverseEvent(partitionEvent);

            if (dataverseEvent.ExecutionContext.PrimaryEntityName == "contact")
            {
                var contactEvents = await MapContactEventsAsync(dataverseEvent.ExecutionContext, cancellationToken);
                businessEvents.AddRange(contactEvents);
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error processing individual event in batch");
            // Continue processing other events in batch
        }
    }

    // Publish all business events in a single batch
    if (businessEvents.Any())
    {
        await PublishBusinessEventBatchAsync(businessEvents, cancellationToken);
    }
}

[TestClass]
public class ContactEventMappingTests
{
    [TestMethod]
    public async Task MapContactEvents_EmailChange_GeneratesBothGenericAndSpecificEvents()
    {
        // Arrange
        var context = CreateContactUpdateContext(
            preEmail: "old@company.com",
            postEmail: "new@company.com");

        var mapper = new BusinessEventMapper(Mock.Of<ILogger<BusinessEventMapper>>());

        // Act
        var events = await mapper.MapContactEventsAsync(context, CancellationToken.None);

        // Assert
        Assert.AreEqual(2, events.Count);

        var genericEvent = events.OfType<ContactUpdated>().FirstOrDefault();
        Assert.IsNotNull(genericEvent);
        Assert.IsTrue(genericEvent.ChangedFields.Contains("emailaddress1"));

        var specificEvent = events.OfType<ContactEmailChanged>().FirstOrDefault();
        Assert.IsNotNull(specificEvent);
        Assert.AreEqual("old@company.com", specificEvent.OldEmailAddress);
        Assert.AreEqual("new@company.com", specificEvent.NewEmailAddress);
        Assert.IsTrue(specificEvent.RequiresEmailVerification);
    }

    [TestMethod]
    public async Task MapContactEvents_OnlyJobTitleChange_GeneratesOnlyGenericEvent()
    {
        // Arrange
        var context = CreateContactUpdateContext(
            preJobTitle: "Developer",
            postJobTitle: "Senior Developer");

        var mapper = new BusinessEventMapper(Mock.Of<ILogger<BusinessEventMapper>>());

        // Act
        var events = await mapper.MapContactEventsAsync(context, CancellationToken.None);

        // Assert
        Assert.AreEqual(1, events.Count);
        Assert.IsInstanceOfType(events[0], typeof(ContactUpdated));

        var genericEvent = (ContactUpdated)events[0];
        Assert.IsTrue(genericEvent.ChangedFields.Contains("jobtitle"));
        Assert.AreEqual("Developer", genericEvent.PreValues["jobtitle"]);
        Assert.AreEqual("Senior Developer", genericEvent.PostValues["jobtitle"]);
    }
}

[TestClass]
public class ContactEventIntegrationTests
{
    private EventHubTestContainer _sourceEventHub;
    private EventHubTestContainer _businessEventHub;
    private ContactEventTranslatorService _translatorService;

    [TestInitialize]
    public async Task Setup()
    {
        _sourceEventHub = new EventHubTestContainer();
        _businessEventHub = new EventHubTestContainer();

        await _sourceEventHub.StartAsync();
        await _businessEventHub.StartAsync();

        _translatorService = new ContactEventTranslatorService(
            _sourceEventHub.ConnectionString,
            _businessEventHub.ConnectionString);
    }

    [TestMethod]
    public async Task EndToEnd_ContactEmailChange_PublishesCorrectEvents()
    {
        // Arrange
        var contactUpdateEvent = CreateDataverseContactUpdateEvent();

        // Act
        await _sourceEventHub.PublishEventAsync(contactUpdateEvent);
        await Task.Delay(5000); // Allow processing time

        // Assert
        var businessEvents = await _businessEventHub.ReadEventsAsync(timeout: TimeSpan.FromSeconds(10));

        Assert.AreEqual(2, businessEvents.Count);

        var contactUpdated = businessEvents.FirstOrDefault(e => e.EventType == "ContactUpdated");
        var emailChanged = businessEvents.FirstOrDefault(e => e.EventType == "ContactEmailChanged");

        Assert.IsNotNull(contactUpdated);
        Assert.IsNotNull(emailChanged);

        // Verify correlation IDs match
        Assert.AreEqual(contactUpdated.CorrelationId, emailChanged.CorrelationId);
    }
}

## Best Practices for Contact Event Translation

### Event Design Principles

1. **Dual Event Strategy**: Always generate both generic `ContactUpdated` events for projections and specific business events for targeted logic
2. **Field-Level Granularity**: Include both pre and post values for changed fields to support different consumer needs
3. **Business Context**: Enrich events with business-relevant computed fields and relationship data
4. **Idempotency**: Ensure events can be safely processed multiple times
5. **Correlation**: Maintain correlation IDs across related events

### Performance Optimization

1. **Field Filtering**: Only process business-relevant field changes to reduce noise
2. **Batch Processing**: Group multiple contact updates when possible to improve throughput
3. **Selective Enrichment**: Only fetch additional data when required by specific business events
4. **Caching**: Cache frequently accessed reference data (like account details for contacts)

### Security Considerations

1. **PII Handling**: Mask or exclude sensitive contact information in generic events
2. **Email Verification**: Implement proper email verification workflows for email changes
3. **Audit Trail**: Log all contact event processing activities for compliance
4. **Data Retention**: Implement appropriate retention policies for contact event data

## Troubleshooting Guide

### Common Contact Event Issues

| Issue | Symptoms | Solution |
|-------|----------|----------|
| Missing Contact Pre/Post Images | Contact events show no field changes | Verify contact-specific image configuration in Plugin Registration Tool |
| Email Verification Not Triggering | ContactEmailChanged events published but no verification emails | Check email change detection logic and verification service integration |
| Duplicate Contact Events | Same contact update generates multiple events | Implement event deduplication based on correlation ID and timestamp |
| Missing Parent Account Context | Contact events lack account relationship data | Ensure parentcustomerid is included in pre/post images |

### Debugging Contact Event Processing

1. **Check Contact-Specific Logs**: Filter logs by contact entity type and correlation ID
2. **Verify Field Detection**: Test field change detection logic with known contact updates
3. **Validate Event Schema**: Ensure contact events match expected schema
4. **Monitor Consumer Lag**: Check if contact event consumers are keeping up with volume
5. **Review Contact Business Logic**: Verify specific business event generation rules

## Conclusion

This solution transforms Dataverse's generic Contact CRUD events into meaningful business events that provide real value to downstream systems. By implementing both generic `ContactUpdated` events for view projections and specific events like `ContactEmailChanged` for business logic, you get the flexibility to support different consumer patterns while maintaining high performance and reliability.

The Contact-focused architecture supports:

- **Flexibility**: Both generic projection events and specific business events from the same source
- **Scalability**: Handle high contact update volumes with Event Hub and containerized processing
- **Reliability**: Built-in retry logic, dead letter queues, and Event Hub durability
- **Observability**: Contact-specific monitoring and alerting
- **Maintainability**: Clean separation between projection and business event logic
- **Extensibility**: Easy to add new contact field monitoring and business events

This approach enables downstream systems to either maintain synchronized contact views through generic events or react to specific contact changes through targeted business events, providing the best of both worlds for event-driven architecture.sharp
public abstract class BusinessEvent
{
    public string EventId { get; set; } = Guid.NewGuid().ToString();
    public string EventType { get; set; }
    public string CorrelationId { get; set; }
    public string SourceEventId { get; set; } // Event Hub sequence number from source event
    public DateTime OccurredAt { get; set; } = DateTime.UtcNow;
    public string SourceSystem { get; set; } = "Dataverse";
    public string EventVersion { get; set; } = "1.0";
    public Dictionary<string, object> Metadata { get; set; } = new Dictionary<string, object>();
}

// Customer Events
public class CustomerCreditLimitChanged : BusinessEvent
{
    public CustomerCreditLimitChanged() { EventType = "CustomerCreditLimitChanged"; }

    public string CustomerId { get; set; }
    public string CustomerName { get; set; }
    public decimal OldCreditLimit { get; set; }
    public decimal NewCreditLimit { get; set; }
    public string ChangedBy { get; set; }
    public string ChangeReason { get; set; }
}

public class CustomerActivated : BusinessEvent
{
    public CustomerActivated() { EventType = "CustomerActivated"; }

    public string CustomerId { get; set; }
    public string CustomerName { get; set; }
    public string Industry { get; set; }
    public string ActivatedBy { get; set; }
}

public class CustomerDeactivated : BusinessEvent
{
    public CustomerDeactivated() { EventType = "CustomerDeactivated"; }

    public string CustomerId { get; set; }
    public string CustomerName { get; set; }
    public string DeactivationReason { get; set; }
    public string DeactivatedBy { get; set; }
}

// Opportunity Events
public class OpportunityWon : BusinessEvent
{
    public OpportunityWon() { EventType = "OpportunityWon"; }

    public string OpportunityId { get; set; }
    public string OpportunityName { get; set; }
    public string CustomerId { get; set; }
    public string CustomerName { get; set; }
    public decimal EstimatedValue { get; set; }
    public decimal ActualValue { get; set; }
    public DateTime CloseDate { get; set; }
    public string WonBy { get; set; }
}

public class OpportunityLost : BusinessEvent
{
    public OpportunityLost() { EventType = "OpportunityLost"; }

    public string OpportunityId { get; set; }
    public string OpportunityName { get; set; }
    public string CustomerId { get; set; }
    public string CustomerName { get; set; }
    public decimal EstimatedValue { get; set; }
    public string LossReason { get; set; }
    public DateTime CloseDate { get; set; }
}

public async Task<List<BusinessEvent>> ProcessEntityUpdate(
    DataverseExecutionContext context, 
    string correlationId, 
    ILogger log)
{
    var events = new List<BusinessEvent>();

    try
    {
        events = context.PrimaryEntityName.ToLower() switch
        {
            "account" => await ProcessAccountUpdate(context, log),
            "opportunity" => await ProcessOpportunityUpdate(context, log),
            "salesorder" => await ProcessOrderUpdate(context, log),
            _ => new List<BusinessEvent>()
        };

        // Add correlation and metadata to all events
        foreach (var evt in events)
        {
            evt.CorrelationId = correlationId;
            evt.Metadata.Add("SourceEntityId", context.PrimaryEntityId.ToString());
            evt.Metadata.Add("SourceEntityType", context.PrimaryEntityName);

            if (context.InitiatingUser != null)
            {
                evt.Metadata.Add("InitiatingUser", context.InitiatingUser.Email);
            }
        }
    }
    catch (Exception ex)
    {
        log.LogError($"Error in ProcessEntityUpdate: {ex.Message}");
        throw;
    }

    return events;
}

private async Task<List<BusinessEvent>> ProcessAccountUpdate(DataverseExecutionContext context, ILogger log)
{
    var events = new List<BusinessEvent>();
    var preImage = context.PreEntityImages["PreImage"];
    var postImage = context.PostEntityImages["PostImage"];
    var accountId = context.PrimaryEntityId.ToString();

    // Credit Limit Changes
    await ProcessCreditLimitChange(preImage, postImage, accountId, events, log);

    // Status Changes
    await ProcessStatusChange(preImage, postImage, accountId, events, log);

    // Contact Information Changes
    await ProcessContactInfoChange(preImage, postImage, accountId, events, log);

    // Industry Changes
    await ProcessIndustryChange(preImage, postImage, accountId, events, log);

    return events;
}

private async Task ProcessCreditLimitChange(
    DataverseEntity preImage, 
    DataverseEntity postImage, 
    string accountId, 
    List<BusinessEvent> events, 
    ILogger log)
{
    var oldCreditLimit = preImage.GetAttributeValue<decimal>("creditlimit");
    var newCreditLimit = postImage.GetAttributeValue<decimal>("creditlimit");

    if (oldCreditLimit != newCreditLimit)
    {
        var customerName = postImage.GetAttributeValue<string>("name");

        events.Add(new CustomerCreditLimitChanged
        {
            CustomerId = accountId,
            CustomerName = customerName,
            OldCreditLimit = oldCreditLimit,
            NewCreditLimit = newCreditLimit,
            ChangeReason = DetermineCreditLimitChangeReason(oldCreditLimit, newCreditLimit)
        });

        log.LogInformation($"Credit limit changed for {customerName} ({accountId}): {oldCreditLimit:C} -> {newCreditLimit:C}");
    }
}

private async Task ProcessStatusChange(
    DataverseEntity preImage, 
    DataverseEntity postImage, 
    string accountId, 
    List<BusinessEvent> events, 
    ILogger log)
{
    var oldStatus = preImage.GetAttributeValue<int>("statuscode");
    var newStatus = postImage.GetAttributeValue<int>("statuscode");

    if (oldStatus != newStatus)
    {
        var customerName = postImage.GetAttributeValue<string>("name");
        var industry = postImage.GetAttributeValue<int>("industrycode");
        var industryName = GetIndustryName(industry);

        // Status codes: 1=Active, 2=Inactive
        if (oldStatus == 2 && newStatus == 1) // Inactive to Active
        {
            events.Add(new CustomerActivated
            {
                CustomerId = accountId,
                CustomerName = customerName,
                Industry = industryName
            });

            log.LogInformation($"Customer activated: {customerName} ({accountId})");
        }
        else if (oldStatus == 1 && newStatus == 2) // Active to Inactive
        {
            events.Add(new CustomerDeactivated
            {
                CustomerId = accountId,
                CustomerName = customerName,
                DeactivationReason = "Status changed to inactive"
            });

            log.LogInformation($"Customer deactivated: {customerName} ({accountId})");
        }
    }
}

private string DetermineCreditLimitChangeReason(decimal oldLimit, decimal newLimit)
{
    if (newLimit > oldLimit)
        return "Credit limit increased";
    else if (newLimit < oldLimit)
        return "Credit limit decreased";
    else
        return "Credit limit adjustment";
}

private string GetIndustryName(int industryCode)
{
    return industryCode switch
    {
        1 => "Technology",
        2 => "Healthcare",
        3 => "Finance",
        4 => "Manufacturing",
        5 => "Retail",
        _ => "Other"
    };
}