bc-code-intelligence-mcp 1.3.3 → 1.3.4

package/embedded-knowledge/domains/dean-debug/custom-telemetry-implementation.md

@@ -1,84 +0,0 @@
----
-title: "Custom Telemetry Implementation in AL"
-domain: "dean-debug"
-difficulty: "intermediate"
-bc_versions: "14+"
-tags: ["telemetry", "session-logmessage", "privacy", "diagnostics", "monitoring"]
-samples: "samples/custom-telemetry.md"
-type: "implementation-pattern"
-category: "diagnostics"
-pattern_type: "good"
-severity: "medium"
-impact_level: "high"
-improvement_suggestion: "Implement custom telemetry for actionable monitoring and diagnostics"
-implementation_steps: ["design-telemetry-schema", "implement-session-logmessage", "validate-privacy-compliance"]
-validation_criteria: ["privacy-compliant", "actionable-data", "performance-neutral"]
-technical_areas: ["al-code", "monitoring"]
----
-
-# Custom Telemetry Implementation in AL
-
-## Overview
-
-Custom telemetry in AL enables developers to emit structured diagnostic data through Session.LogMessage() for Application Insights integration. This observability foundation supports proactive monitoring, performance analysis, and troubleshooting while maintaining strict privacy compliance.
-
-**Critical Principle**: Treat telemetry as an API - documented, versioned, discoverable, and non-breaking for downstream analytics consumers.
-
-## Strategic Framework
-
-### Telemetry Design Philosophy
-- **Actionable Data Only**: Emit signals customers can act upon, avoiding noise from non-actionable metrics
-- **Privacy by Design**: Never log PII, customer data, or sensitive business information
-- **Cost Consciousness**: Balance diagnostic value with data ingestion costs through intelligent sampling
-- **Schema Consistency**: Use standardized naming conventions and structured dimensions
-
-### When to Implement Custom Telemetry
-- **Error Deflection**: Authentication failures, permission issues, configuration problems
-- **Performance Monitoring**: Long-running operations, resource bottlenecks, timeout scenarios
-- **Feature Adoption**: Usage patterns, workflow completion rates, feature discovery
-- **Integration Health**: External service calls, API responses, data synchronization status
-
-## Architecture Focus
-
-### Session.LogMessage() Implementation Pattern
-Structure telemetry calls with consistent event IDs, descriptive messages following "Object ActionInPastTense" pattern, and appropriate verbosity levels. Use custom dimensions dictionary for structured data while maintaining PascalCasing conventions.
-
-### Privacy-Compliant Data Classification
-Always use DataClassification::SystemMetadata for telemetry events. Review all LogMessage calls for potential privacy violations before production deployment. Focus on operational metadata rather than business data.
-
-### Telemetry Scope Strategy
-Default to TelemetryScope::ExtensionPublisher to control costs. Use TelemetryScope::All only when customers can directly act on the telemetry data for their business operations.
-
-## Best Practices
-
-### Implementation Guidelines
-- **Object-Level Emission**: Call Session.LogMessage() from within objects causing situations requiring telemetry
-- **Structured Dimensions**: Use Dictionary of [Text,Text] for custom dimensions with meaningful prefixes
-- **Message Consistency**: Always include human-readable "message" field expressing event purpose
-- **Correlation Support**: Include identifiers enabling distributed tracing across system boundaries
-
-### Performance Considerations
-- **Non-Blocking**: Ensure telemetry calls never impact user experience or application performance
-- **Minimal Processing**: Avoid complex calculations within telemetry emission paths
-- **Sampling Strategy**: Implement intelligent sampling for high-frequency events
-
-### Analytics Integration
-Design telemetry for Application Insights consumption with KQL-friendly field names, consistent schemas across related events, and dimensions supporting common analytical queries.
-
-## Anti-Patterns
-
-### Avoid These Approaches
-- **Privacy Violations**: Logging customer data, PII, or sensitive business information
-- **Telemetry Flooding**: Excessive volume without considering customer ingestion costs
-- **Functional Dependencies**: Using telemetry data for application logic rather than pure observability
-- **Inconsistent Schemas**: Different naming patterns across related telemetry events
-
-### Common Implementation Mistakes
-- Missing privacy review before production deployment
-- Using special characters or spaces in custom dimension keys
-- Emitting telemetry from central objects rather than originating sources
-- Failing to provide actionable information for intended telemetry consumers
-
-*Implementation examples: see samples/custom-telemetry.md*
-*Privacy guidelines: see privacy-compliance-patterns.md*
-*Related patterns: monitoring-strategy.md, error-handling-patterns.md*

package/embedded-knowledge/domains/dean-debug/deleteall-performance-tradeoff.md

@@ -1,93 +0,0 @@
----
-title: "DeleteAll Performance Tradeoff"
-domain: "dean-debug"
-difficulty: "intermediate"
-bc_versions: "14+"
-tags: ["deleteall", "performance", "optimization", "tradeoffs"]
-prerequisites: ["deleteall-method-usage", "performance-fundamentals"]
-samples: "samples/deleteall-performance.md"
----
-# DeleteAll Performance Tradeoff
-
-## Overview
-
-DeleteAll presents a fundamental performance tradeoff in BC: business logic compliance versus execution speed. While DeleteAll ensures complete business rule enforcement through OnDelete trigger execution, this comprehensive approach comes with significant performance implications.
-
-**Core Tradeoff**: Business logic completeness versus execution performance - DeleteAll prioritizes data integrity over speed.
-
-**Performance Reality**: DeleteAll operations typically perform 10-100x slower than direct SQL deletions due to individual record processing and trigger execution overhead.
-
-## Strategic Framework
-
-### Performance Cost Analysis
-
-**Execution Overhead Sources**:
-- Individual record processing rather than set-based operations
-- OnDelete trigger execution for every deleted record
-- Related table operations multiplying database interactions
-- Validation logic execution adding computational overhead
-- Transaction management extending operation duration
-
-### Business Value Assessment
-
-**Data Integrity Benefits**:
-- Complete business rule enforcement during deletion operations
-- Proper audit trail and logging maintenance
-- Cascade delete operations preserving referential integrity
-- Custom validation logic execution ensuring data consistency
-- Related table synchronization maintaining system coherence
-
-## Performance Impact Prediction
-
-### Record Volume Sensitivity
-- Small datasets (< 1000 records): Performance impact typically acceptable
-- Medium datasets (1000-10000 records): Noticeable but manageable impact
-- Large datasets (> 10000 records): Significant performance degradation likely
-- Very large datasets (> 100000 records): Potentially prohibitive execution times
-
-### Trigger Complexity Multiplier
-- Simple OnDelete triggers: Minimal additional overhead per record
-- Moderate trigger logic: 2-5x performance impact multiplication
-- Complex trigger operations: 10-50x performance impact multiplication
-- External system integration: Unpredictable and potentially severe impact
-
-## Decision Guidelines
-
-### When to Use DeleteAll
-- Business logic enforcement is critical for data integrity
-- Audit trail and logging must be maintained
-- Cascade delete operations are required
-- Related table synchronization is necessary
-- Custom validation logic must execute during deletion
-
-### When to Consider Alternatives
-- Simple cleanup operations without business logic requirements
-- System maintenance operations where speed is critical
-- Temporary data removal with minimal related table impact
-- Bulk operations on isolated tables without complex relationships
-
-## Best Practices
-
-### Performance-Conscious Implementation
-- Limit DeleteAll operations to appropriate dataset sizes based on system capacity
-- Schedule large DeleteAll operations during low-usage periods
-- Implement batch processing for large datasets requiring business logic enforcement
-- Monitor system performance during deletion operations
-
-### Decision Making Framework
-- Identify specific business logic requirements for deletion operations
-- Evaluate data integrity criticality versus performance needs
-- Assess related table impact and cascade operation requirements
-- Determine acceptable performance thresholds for user experience
-
-## Anti-Patterns
-
-### Performance Expectations Mismatch
-**Incorrect Assumption**: Expecting DeleteAll to perform comparably to direct SQL operations. DeleteAll prioritizes business logic compliance over speed, and trigger execution overhead is inherent.
-
-### Inappropriate Usage Scenarios
-**Wrong Application**: Using DeleteAll for simple cleanup operations without business logic needs. Reserve DeleteAll for scenarios where business logic enforcement justifies performance cost.
-
-### Scale Misunderstanding
-**Problematic Planning**: Underestimating performance impact at scale. Test DeleteAll performance with realistic production data volumes and complexity before implementation.
-

package/embedded-knowledge/domains/dean-debug/deleteall-sql-performance.md

@@ -1,73 +0,0 @@
----
-title: "DeleteAll SQL Translation and Performance Impact"
-domain: "dean-debug"
-difficulty: "intermediate"
-bc_versions: "14+"
-tags: ["deleteall", "sql-translation", "performance-optimization"]
-samples: "samples/deleteall-performance.md"
-type: "improvement-pattern"
-category: "performance-optimization"
-pattern_type: "good"
-severity: "medium"
-impact_level: "high"
-improvement_suggestion: "Use DeleteAll for bulk deletions to leverage SQL DELETE performance"
-implementation_steps: ["identify-bulk-deletion-scenarios", "replace-iterative-loops", "validate-event-dependencies"]
-validation_criteria: ["performance-benchmarks", "event-dependency-analysis"]
-technical_areas: ["al-code", "database"]
----
-
-# DeleteAll SQL Translation and Performance Impact
-
-## Overview
-
-DeleteAll method translates directly to SQL DELETE statements, providing significant performance advantages over iterative record deletion. This single SQL operation eliminates AL runtime overhead but bypasses table-level AL events, creating critical performance vs. event consistency trade-offs.
-
-**Key Insight**: DeleteAll executes as one database operation rather than individual record processing, dramatically improving performance for large datasets while skipping AL-level validations.
-
-## Strategic Framework
-
-### Performance Characteristics
-- **Single SQL DELETE**: Entire operation executes as one database statement
-- **Eliminates AL Overhead**: No per-record AL runtime processing
-- **Database-Level Execution**: Constraints and triggers still execute
-- **Bypasses AL Events**: OnDelete triggers and validations are skipped
-
-### When to Use DeleteAll
-- **Large Record Sets**: Performance gains most pronounced with bulk deletions
-- **Simple Deletion Logic**: No complex AL validation required
-- **Performance Critical**: Operations where speed is prioritized
-- **Database Constraints Sufficient**: Referential integrity handled at database level
-
-## Architecture Focus
-
-### SQL Translation Impact
-DeleteAll converts to optimized SQL DELETE with WHERE clauses matching record filters. Database engine handles the bulk operation efficiently using index structures and internal optimization strategies.
-
-### Event Processing Differences
-Table-level AL events (OnDelete triggers, validation logic) are completely bypassed. Only database-level constraints and triggers execute, creating potential inconsistencies with iterative deletion behavior.
-
-### Memory and Resource Efficiency
-Single SQL operation uses minimal AL runtime resources compared to loop-based deletion that processes each record through full AL stack.
-
-## Best Practices
-
-### Performance Optimization
-- **Bulk Operations**: Prefer DeleteAll for large dataset removals
-- **Filter Optimization**: Ensure filters use indexed fields for optimal SQL execution
-- **Transaction Boundaries**: Consider transaction scope for very large deletions
-- **Resource Monitoring**: Monitor database resource usage during bulk operations
-
-### Event Dependency Management
-- **Validate Dependencies**: Ensure no critical AL logic exists in bypassed events
-- **Alternative Patterns**: Implement necessary validations before DeleteAll execution
-- **Documentation**: Document event bypass behavior for maintenance clarity
-
-## Anti-Patterns
-
-### Avoid These Approaches
-- Using DeleteAll when AL events contain critical business logic
-- Iterative deletion loops for performance-critical bulk operations
-- Ignoring database constraint dependencies during bulk deletions
-- Mixing DeleteAll with individual record processing without understanding event differences
-
-*Implementation examples: see samples/deleteall-performance.md*

package/embedded-knowledge/domains/dean-debug/extension-telemetry-isolation.md

@@ -1,78 +0,0 @@
----
-title: "Extension Telemetry Isolation"
-domain: "dean-debug"
-difficulty: "intermediate"
-bc_versions: "14+"
-tags: ["telemetry", "extensions", "isolation", "multi-tenancy"]
-prerequisites: ["custom-dimensions-best-practices"]
-samples: "samples/extension-isolation.md"
----
-# Extension Telemetry Isolation
-
-## Overview
-
-Extension telemetry isolation ensures that telemetry events from different extensions can be independently monitored, analyzed, and troubleshot without interference. Proper isolation enables extension publishers to monitor their components separately while supporting comprehensive system-wide analysis.
-
-Telemetry isolation becomes critical in multi-extension environments where different publishers need independent monitoring capabilities and where system administrators require the ability to analyze issues by extension scope.
-
-## Isolation Strategies
-
-### Extension Identification
-Include consistent extension identification in all telemetry events through custom dimensions. Use extension publisher information, extension name, and version details to enable filtering and analysis by extension scope.
-
-Implement standardized extension identification patterns that work across all extensions and enable consistent filtering in monitoring systems. Consider using the extension's App ID as a reliable identification mechanism.
-
-### Namespace Separation
-Design telemetry event naming conventions that include extension context to prevent naming conflicts between extensions. Use prefixed event names or structured naming that clearly identifies the source extension.
-
-Namespace separation enables independent analysis while preventing confusion when multiple extensions emit similar telemetry event types.
-
-### Custom Dimension Isolation
-Use extension-specific custom dimension naming to prevent dimension name conflicts between extensions. Implement dimension naming conventions that include extension context while maintaining analytical capability.
-
-Consider using dimension namespaces or prefixes that clearly identify the source extension while enabling cross-extension analysis where appropriate.
-
-## Multi-Tenant Considerations
-
-### Tenant Isolation
-Ensure telemetry isolation works effectively in multi-tenant environments where multiple tenants may use the same extensions. Combine extension isolation with tenant identification to enable both extension-specific and tenant-specific analysis.
-
-Design isolation patterns that scale across large multi-tenant deployments while maintaining performance and analytical capability.
-
-### Cross-Tenant Analysis
-Consider scenarios where extension publishers need to analyze telemetry across multiple tenant installations. Design isolation patterns that enable this analysis while respecting tenant data privacy and security requirements.
-
-## Implementation Patterns
-
-### Extension Context Propagation
-Propagate extension identification consistently throughout business process execution, including scenarios where multiple extensions interact. Ensure extension context flows through integration boundaries and system interactions.
-
-Use parameter passing or context objects to maintain extension identification throughout complex business processes that span multiple components or extensions.
-
-### Shared Resource Monitoring
-Design telemetry patterns for monitoring shared resources (like database tables or integration endpoints) that are accessed by multiple extensions. Enable analysis by extension while maintaining visibility into overall resource utilization.
-
-### Extension Interaction Tracking
-Implement telemetry patterns that track interactions between different extensions. This capability supports troubleshooting scenarios where issues arise from extension interactions or dependencies.
-
-## Analysis and Monitoring
-
-### Extension-Specific Dashboards
-Create monitoring dashboards that filter telemetry by extension scope. Enable extension publishers to monitor their components independently while providing system administrators with comprehensive system views.
-
-### Cross-Extension Analysis
-Design analysis capabilities that can examine interactions between extensions while respecting isolation boundaries. Support troubleshooting scenarios where issues span multiple extensions.
-
-### Performance Impact Isolation
-Enable analysis of performance impact by extension to identify which extensions contribute to system performance issues. Use extension identification to isolate performance telemetry and enable targeted optimization efforts.
-
-## Troubleshooting Applications
-
-### Extension-Specific Issues
-Use extension isolation to focus troubleshooting efforts on specific extensions when issues are identified. Filter telemetry to specific extensions to reduce noise and accelerate root cause identification.
-
-### Integration Issue Analysis
-Leverage extension isolation when troubleshooting integration issues that may involve multiple extensions. Analyze telemetry from each involved extension to understand interaction patterns and identify failure points.
-
-### Performance Investigation
-Use extension isolation to identify performance bottlenecks attributable to specific extensions. Analyze resource utilization and operation timing by extension scope to guide optimization efforts.

package/embedded-knowledge/domains/dean-debug/maintainsiftindex-property-behavior.md

@@ -1,79 +0,0 @@
----
-title: "MaintainSIFTIndex Property Behavior"
-domain: "dean-debug"
-difficulty: "intermediate"
-bc_versions: "14+"
-tags: ["sift", "performance", "indexing", "optimization", "table-configuration"]
-prerequisites: ["sift-basics", "table-keys"]
-related_topics: ["sift-tuning", "key-optimization"]
-samples: "samples/maintainsiftindex-examples.md"
----
-# MaintainSIFTIndex Property Behavior
-
-## Overview
-
-MaintainSIFTIndex controls whether Business Central automatically maintains SIFT index structures for a key during data modifications. This property directly impacts both query performance and modification overhead, requiring careful balance between read and write operations.
-
-**Critical Decision**: Set MaintainSIFTIndex=Yes only when SIFT queries significantly outweigh modification operations on the indexed fields.
-
-## Property Behavior Analysis
-
-### MaintainSIFTIndex=Yes
-- **Real-time index updates** during INSERT/MODIFY/DELETE operations
-- **Immediate SIFT availability** for queries without rebuild delays
-- **Higher modification overhead** due to index maintenance
-- **Consistent query performance** regardless of data changes
-
-### MaintainSIFTIndex=No  
-- **Deferred index maintenance** until SIFT queries execute
-- **Lower modification overhead** during data entry operations
-- **Potential query delays** while indexes rebuild on first access
-- **Variable query performance** based on index freshness
-
-## Performance Trade-off Framework
-
-### Use MaintainSIFTIndex=Yes When
-- **High query frequency** on SIFT fields (>10x modification rate)
-- **Real-time reporting requirements** demand immediate data availability
-- **Batch processing scenarios** where query performance is critical
-- **Read-heavy workloads** with infrequent data modifications
-
-### Use MaintainSIFTIndex=No When
-- **High modification frequency** exceeds query requirements
-- **Data entry intensive operations** where speed is paramount
-- **Batch import scenarios** with subsequent query phases
-- **Memory-constrained environments** requiring reduced overhead
-
-## Decision Criteria Matrix
-
-### Workload Assessment
-Evaluate modification-to-query ratios for each key. Keys with modification rates >3x query rates typically benefit from MaintainSIFTIndex=No, while query-heavy keys (>5x query rate) should use MaintainSIFTIndex=Yes.
-
-### Resource Considerations  
-Consider available memory and CPU resources. High-modification environments with limited resources may require selective MaintainSIFTIndex=No settings to maintain overall system performance.
-
-## Implementation Best Practices
-
-### Strategic Configuration
-- **Profile actual usage patterns** before setting property values
-- **Monitor SIFT performance metrics** after configuration changes
-- **Document rationale** for each MaintainSIFTIndex decision
-- **Regular reassessment** as business processes evolve
-
-### Testing Approach
-Test both settings under realistic data volumes and usage patterns. Performance differences may not be apparent with small datasets but become critical at production scale.
-
-## Common Configuration Mistakes
-
-### Anti-Patterns to Avoid
-- **Default Yes everywhere** without workload analysis
-- **Inconsistent settings** across related keys without justification  
-- **Ignoring modification overhead** in data-entry intensive processes
-- **Setting without monitoring** performance impact post-implementation
-
-### Validation Criteria
-Verify configuration effectiveness through SIFT performance monitoring, modification operation timing, and overall system resource utilization patterns.
-
-*Complete SIFT optimization guide: see SIFT pattern documentation*
-*Implementation samples: see samples/maintainsiftindex-examples.md*
-*Performance monitoring: see SIFT metadata indexes documentation*

package/embedded-knowledge/domains/dean-debug/no-series-implementation-patterns.md

@@ -1,87 +0,0 @@
----
-title: "No Series Implementation Patterns"
-domain: "dean-debug"
-difficulty: "intermediate"
-bc_versions: "14..23"
-tags: ["no-series", "number-generation", "sequence-management", "business-infrastructure"]
-prerequisites: ["table-design", "no-series-basics", "business-logic-patterns"]
-samples: "samples/no-series-implementation.md"
-related_topics: ["no-series-validation-patterns", "data-integrity-patterns"]
----
-
-# No Series Implementation Patterns
-
-## Overview
-
-No Series Implementation Patterns provide robust approaches for implementing automatic number generation in Business Central applications. These patterns ensure unique, sequential numbering for business documents while handling concurrency, gaps, and performance requirements.
-
-**Key Benefit**: Provides reliable, scalable number generation that maintains data integrity and supports high-concurrency scenarios while meeting business numbering requirements.
-
-## Core Implementation Architecture
-
-### Number Generation Strategy
-Design number generation systems that balance uniqueness requirements, performance needs, and gap handling policies based on business requirements.
-
-### Concurrency Management
-Implement concurrency controls that prevent number conflicts when multiple users create documents simultaneously.
-
-### Gap Handling Policies
-Design gap handling strategies that align with business requirements for number sequence continuity and audit compliance.
-
-## Essential Implementation Patterns
-
-### Standard No Series Integration
-Leverage Business Central's built-in No Series functionality effectively while extending it for specific business requirements.
-
-### Custom Number Generation
-Implement custom numbering schemes for scenarios where standard No Series functionality doesn't meet specific business needs.
-
-### Multi-Dimensional Numbering
-Design numbering systems that incorporate multiple dimensions (company, location, document type) while maintaining uniqueness.
-
-## Advanced Implementation Techniques
-
-### Performance-Optimized Generation
-Implement number generation patterns that minimize database locks and support high-throughput document creation scenarios.
-
-### Distributed Number Generation
-Design numbering systems that work effectively across multiple Business Central instances or integration scenarios.
-
-### Intelligent Gap Management
-Create gap management systems that can detect and optionally fill gaps based on business policies and compliance requirements.
-
-## Concurrency and Locking Patterns
-
-### Lock Minimization Strategies
-- Implement number generation that minimizes database lock duration
-- Use optimistic locking patterns where appropriate for performance
-- Design lock escalation strategies for high-contention scenarios
-- Support lock timeout handling and retry mechanisms
-
-### Transaction Coordination
-- Coordinate number generation with business transaction boundaries
-- Handle rollback scenarios and number sequence implications
-- Support distributed transaction scenarios with proper number handling
-- Implement compensation patterns for failed number generation
-
-## Advanced Features
-
-### Performance & Integration
-Implement batch allocation, caching strategies, robust error handling, and external system coordination for enterprise scenarios.
-
-## Quality Assurance
-
-### Validation & Integrity
-Implement comprehensive validation, integrity monitoring, and policy-driven numbering with multi-format support.
-
-## Implementation Guidelines
-
-### Testing & Best Practices
-Test concurrency scenarios, implement comprehensive logging, and provide clear documentation with monitoring capabilities.
-
-### Common Pitfalls
-Avoid concurrency issues, performance bottlenecks, and gap accumulation through proper design and testing.
-
-*Complete no series implementation examples: samples/no-series-implementation.md*
-*Number validation patterns: no-series-validation-patterns.md*
-*Data integrity patterns: data-integrity-patterns.md*