@jwikman/bc-code-intelligence-mcp 1.5.7-dev.1

package/embedded-knowledge/domains/eva-errors/samples/table-safety-validation-patterns.md

@@ -0,0 +1,101 @@
+# Table Safety Validation Patterns
+
+## IsTemporary Safeguard Implementation
+```al
+procedure ProcessBulkData(var DataBuffer: Record "Data Processing Buffer")
+begin
+    // Always validate temporary status before bulk operations
+    if not DataBuffer.IsTemporary then
+        Error('This procedure requires a temporary table to prevent data corruption.');
+        
+    DataBuffer.Reset();
+    if DataBuffer.FindSet() then
+        repeat
+            ProcessIndividualRecord(DataBuffer);
+            DataBuffer.Delete(); // Safe because table is confirmed temporary
+        until DataBuffer.Next() = 0;
+end;
+```
+
+## Database Write Protection
+```al
+procedure SafeDataManipulation(var TempCustomer: Record Customer temporary)
+var
+    Customer: Record Customer;
+begin
+    // Validate temporary status before any modifications
+    if not TempCustomer.IsTemporary then
+        Error('Database safety violation: Expected temporary table for data manipulation.');
+        
+    // Safe to perform destructive operations
+    TempCustomer.Reset();
+    TempCustomer.DeleteAll();
+    
+    // Load fresh data from permanent table
+    Customer.FindSet();
+    repeat
+        TempCustomer := Customer;
+        TempCustomer.Insert();
+    until Customer.Next() = 0;
+end;
+```
+
+## Bulk Operation Validation
+```al
+procedure ProcessLargeDataSet(var TempItem: Record Item temporary; ProcessingMode: Option Validate,Update,Delete)
+begin
+    // Critical safety check for bulk operations
+    if not TempItem.IsTemporary then
+        Error('Bulk processing operations require temporary tables. This prevents accidental permanent data modification.');
+        
+    case ProcessingMode of
+        ProcessingMode::Validate:
+            ValidateAllRecords(TempItem);
+        ProcessingMode::Update:
+            UpdateAllRecords(TempItem);
+        ProcessingMode::Delete:
+            TempItem.DeleteAll(); // Safe deletion
+    end;
+end;
+
+local procedure ValidateAllRecords(var TempItem: Record Item temporary)
+begin
+    TempItem.Reset();
+    if TempItem.FindSet() then
+        repeat
+            ValidateItemData(TempItem);
+        until TempItem.Next() = 0;
+end;
+```
+
+## Data Integrity Protection
+```al
+procedure SecureDataProcessing(var WorkingTable: Record "Working Data Buffer")
+var
+    OriginalFilters: Text;
+begin
+    // Mandatory safety validation
+    if not WorkingTable.IsTemporary then
+        Error('Data integrity protection: This operation requires a temporary working table.');
+        
+    OriginalFilters := WorkingTable.GetFilters();
+    
+    try
+        WorkingTable.Reset();
+        ProcessAllRecords(WorkingTable);
+    finally
+        // Restore original state
+        WorkingTable.Reset();
+        WorkingTable.SetView(OriginalFilters);
+    end;
+end;
+
+local procedure ProcessAllRecords(var WorkingTable: Record "Working Data Buffer")
+begin
+    if WorkingTable.FindSet(true) then
+        repeat
+            WorkingTable."Processing Status" := WorkingTable."Processing Status"::Completed;
+            WorkingTable.Modify();
+        until WorkingTable.Next() = 0;
+end;
+```

package/embedded-knowledge/domains/eva-errors/samples/testfield-error-handling.md

@@ -0,0 +1,108 @@
+# TestField Error Handling Patterns
+
+## Try-Catch with TestField
+```al
+procedure ValidateDocumentSafely(var SalesHeader: Record "Sales Header"): Boolean
+begin
+    if not TryValidateDocument(SalesHeader) then begin
+        LogValidationError(GetLastErrorText());
+        exit(false);
+    end;
+    exit(true);
+end;
+
+local procedure TryValidateDocument(var SalesHeader: Record "Sales Header")
+begin
+    SalesHeader.TestField("Document Type");
+    SalesHeader.TestField("No.");
+    SalesHeader.TestField("Sell-to Customer No.");
+end;
+```
+
+## Batch Validation with Error Collection
+```al
+procedure ValidateCustomerBatch(var TempCustomer: Record Customer temporary): Text
+var
+    ErrorMessages: Text;
+    Customer: Record Customer;
+begin
+    TempCustomer.Reset();
+    if TempCustomer.FindSet() then
+        repeat
+            Customer := TempCustomer;
+            if not TryValidateCustomer(Customer) then
+                ErrorMessages += StrSubstNo('Customer %1: %2\', Customer."No.", GetLastErrorText());
+        until TempCustomer.Next() = 0;
+    
+    exit(ErrorMessages);
+end;
+
+local procedure TryValidateCustomer(Customer: Record Customer): Boolean
+begin
+    Customer.TestField(Name);
+    Customer.TestField("Customer Posting Group");
+    exit(true);
+end;
+```
+
+## Conditional TestField with Fallback
+```al
+procedure ValidateVendorWithDefaults(var Vendor: Record Vendor)
+var
+    VendorPostingGroup: Record "Vendor Posting Group";
+begin
+    if not TryTestVendorFields(Vendor) then begin
+        // Apply defaults and retry
+        if Vendor."Vendor Posting Group" = '' then begin
+            VendorPostingGroup.FindFirst();
+            Vendor."Vendor Posting Group" := VendorPostingGroup.Code;
+        end;
+        
+        // Retry validation
+        Vendor.TestField("Vendor Posting Group");
+    end;
+end;
+
+local procedure TryTestVendorFields(Vendor: Record Vendor): Boolean
+begin
+    Vendor.TestField("Vendor Posting Group");
+    exit(true);
+end;
+```
+
+## Graceful Degradation Pattern
+```al
+procedure ProcessOrderWithValidation(var SalesHeader: Record "Sales Header"): Boolean
+var
+    ValidationLevel: Integer;
+begin
+    // Try strict validation first
+    ValidationLevel := 1;
+    if TryValidateOrderStrict(SalesHeader) then
+        exit(true);
+    
+    // Fall back to basic validation
+    ValidationLevel := 2;
+    if TryValidateOrderBasic(SalesHeader) then begin
+        LogWarning('Order %1 processed with basic validation only', SalesHeader."No.");
+        exit(true);
+    end;
+    
+    exit(false);
+end;
+
+local procedure TryValidateOrderStrict(SalesHeader: Record "Sales Header"): Boolean
+begin
+    SalesHeader.TestField("External Document No.");
+    SalesHeader.TestField("Requested Delivery Date");
+    SalesHeader.TestField("Shipment Method Code");
+    exit(true);
+end;
+
+local procedure TryValidateOrderBasic(SalesHeader: Record "Sales Header"): Boolean
+begin
+    SalesHeader.TestField("Sell-to Customer No.");
+    SalesHeader.TestField("Order Date");
+    exit(true);
+end;
+```

package/embedded-knowledge/domains/eva-errors/samples/try-function-usage.md

@@ -0,0 +1,195 @@
+# Try Function Usage Samples
+
+## External Web Service Call
+```al
+procedure CallExternalAPI(CustomerNo: Code[20]): Boolean
+var
+    CustomerData: JsonObject;
+begin
+    // Prepare data OUTSIDE try function
+    CustomerData := PrepareCustomerPayload(CustomerNo);
+    
+    // External call INSIDE try function
+    if not TrySendToExternalAPI(CustomerData) then begin
+        LogAPIError(CustomerNo, GetLastErrorText());
+        exit(false);
+    end;
+    
+    // Database write OUTSIDE try function
+    MarkCustomerAsSynced(CustomerNo);
+    exit(true);
+end;
+
+[TryFunction]
+local procedure TrySendToExternalAPI(Payload: JsonObject)
+var
+    Client: HttpClient;
+    Response: HttpResponseMessage;
+    Content: HttpContent;
+begin
+    Content.WriteFrom(Payload.AsText());
+    Client.Post('https://api.example.com/customers', Content, Response);
+    
+    if not Response.IsSuccessStatusCode() then
+        Error('API returned status %1', Response.HttpStatusCode());
+end;
+```
+
+## Batch Validation Pattern
+```al
+procedure ValidateImportBatch(var TempImportBuffer: Record "Import Buffer" temporary): Boolean
+var
+    AllValid: Boolean;
+    ErrorLog: Text;
+begin
+    AllValid := true;
+    
+    if TempImportBuffer.FindSet() then
+        repeat
+            // Read-only validation in try function
+            if not TryValidateImportRecord(TempImportBuffer) then begin
+                AllValid := false;
+                ErrorLog += StrSubstNo('Line %1: %2\', 
+                    TempImportBuffer."Line No.", GetLastErrorText());
+            end;
+        until TempImportBuffer.Next() = 0;
+    
+    if not AllValid then
+        Message('Validation errors:\%1', ErrorLog);
+    
+    exit(AllValid);
+end;
+
+[TryFunction]
+local procedure TryValidateImportRecord(ImportBuffer: Record "Import Buffer" temporary)
+var
+    Customer: Record Customer;
+    Item: Record Item;
+begin
+    // These are read-only checks - safe in try function
+    Customer.Get(ImportBuffer."Customer No.");
+    Item.Get(ImportBuffer."Item No.");
+    
+    if ImportBuffer.Quantity <= 0 then
+        Error('Quantity must be positive');
+    
+    if ImportBuffer."Unit Price" < 0 then
+        Error('Unit price cannot be negative');
+end;
+```
+
+## File Operation Wrapper
+```al
+procedure ProcessImportFile(FilePath: Text): Boolean
+var
+    FileContent: Text;
+begin
+    if not TryReadFile(FilePath, FileContent) then begin
+        LogError('File read failed: ' + GetLastErrorText());
+        exit(false);
+    end;
+    
+    // Process content and write to database OUTSIDE try
+    ProcessFileContent(FileContent);
+    exit(true);
+end;
+
+[TryFunction]
+local procedure TryReadFile(FilePath: Text; var Content: Text)
+var
+    InStream: InStream;
+    TempBlob: Codeunit "Temp Blob";
+    FileManagement: Codeunit "File Management";
+begin
+    FileManagement.BLOBImportFromServerFile(TempBlob, FilePath);
+    TempBlob.CreateInStream(InStream);
+    InStream.ReadText(Content);
+end;
+```
+
+## WRONG: Write Operations Inside Try Function
+```al
+// ❌ THIS IS WRONG - DO NOT DO THIS
+[TryFunction]
+local procedure TryUpdateCustomerStatus(CustomerNo: Code[20])
+var
+    Customer: Record Customer;
+begin
+    Customer.Get(CustomerNo);
+    Customer.Status := Customer.Status::Active;  
+    Customer.Modify();  // ❌ WRITE OPERATION INSIDE TRY - NOT ALLOWED
+end;
+```
+
+## CORRECT: Separation of Concerns
+```al
+// ✅ CORRECT PATTERN
+procedure UpdateCustomerStatusSafely(CustomerNo: Code[20]): Boolean
+var
+    Customer: Record Customer;
+begin
+    // Validate in try function (read-only)
+    if not TryValidateCustomerForActivation(CustomerNo) then begin
+        LogError(CustomerNo, GetLastErrorText());
+        exit(false);
+    end;
+    
+    // Write operation OUTSIDE try function
+    Customer.Get(CustomerNo);
+    Customer.Status := Customer.Status::Active;
+    Customer.Modify();
+    exit(true);
+end;
+
+[TryFunction]
+local procedure TryValidateCustomerForActivation(CustomerNo: Code[20])
+var
+    Customer: Record Customer;
+begin
+    Customer.Get(CustomerNo);
+    Customer.TestField("Payment Terms Code");
+    Customer.TestField("Customer Posting Group");
+    
+    if Customer.Balance > Customer."Credit Limit" then
+        Error('Customer exceeds credit limit');
+end;
+```
+
+## HTTP Client with Retry Logic
+```al
+procedure CallAPIWithRetry(Endpoint: Text; var ResponseText: Text): Boolean
+var
+    RetryCount: Integer;
+    MaxRetries: Integer;
+begin
+    MaxRetries := 3;
+    
+    for RetryCount := 1 to MaxRetries do begin
+        if TryCallAPI(Endpoint, ResponseText) then
+            exit(true);
+        
+        // Log retry attempt
+        LogInfo(StrSubstNo('API call attempt %1 failed: %2', 
+            RetryCount, GetLastErrorText()));
+        
+        if RetryCount < MaxRetries then
+            Sleep(1000 * RetryCount);  // Exponential backoff
+    end;
+    
+    LogError('API call failed after ' + Format(MaxRetries) + ' attempts');
+    exit(false);
+end;
+
+[TryFunction]
+local procedure TryCallAPI(Endpoint: Text; var ResponseText: Text)
+var
+    Client: HttpClient;
+    Response: HttpResponseMessage;
+begin
+    Client.Get(Endpoint, Response);
+    Response.Content().ReadAs(ResponseText);
+    
+    if not Response.IsSuccessStatusCode() then
+        Error('HTTP %1: %2', Response.HttpStatusCode(), ResponseText);
+end;
+```

package/embedded-knowledge/domains/eva-errors/testfield-error-handling.md

@@ -0,0 +1,80 @@
+---
+title: "TestField Error Handling and Custom Messages"
+domain: "eva-errors"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["error-handling", "validation", "user-experience", "custom-messages"]
+prerequisites: ["testfield-basic-syntax", "error-handling-fundamentals"]
+samples: "samples/testfield-error-handling.md"
+---
+# TestField Error Handling and Custom Messages
+
+## Overview
+
+TestField generates automatic error messages, but business scenarios often require custom error handling and messaging. Understanding TestField error behavior enables better user experience and error management strategies.
+
+**Key Principle**: TestField errors are runtime exceptions that halt procedure execution unless caught and handled.
+
+## Default Error Behavior
+
+### Standard Error Messages
+TestField generates system messages like "You must specify Name in Customer" when validation fails. These messages include:
+- Field caption from table definition
+- Table name
+- Current record context when available
+
+### Error Flow Impact
+TestField errors immediately terminate current procedure execution. Control returns to calling code or user interface with error state.
+
+## Custom Error Handling Patterns
+
+### Try-Function Approach
+Wrap TestField calls in TryFunction procedures to catch validation errors without terminating execution. Returns boolean success indicator for error-tolerant processing scenarios.
+
+### Custom Validation with Better Messages
+Replace TestField with custom validation logic when business context requires specific error messages. Provides more meaningful feedback to users than system-generated messages.
+
+### Conditional TestField Usage
+Apply TestField validation based on business rules or record state. Ensures appropriate validation intensity for different scenarios without over-validating.
+
+## Advanced Error Management
+
+### Error Context Enhancement
+Capture TestField errors using TryFunction pattern and enhance with business context before re-throwing. Provides users with meaningful error information including document details.
+
+### Multiple Field Validation with Aggregated Errors
+Collect multiple validation failures before reporting to users. Improves user experience by showing all validation issues at once rather than one-by-one error correction.
+
+## Integration with Business Logic
+
+### Workflow Integration
+TestField works seamlessly with workflow validations. Use TestField for mandatory data checks within workflow step validations.
+
+### API Integration
+For API endpoints, catch TestField errors and return structured error responses rather than allowing raw BC errors to propagate.
+
+### Batch Processing
+In batch processing scenarios, use TryFunction pattern to continue processing other records when individual record validation fails.
+
+## User Experience Considerations
+
+### Progressive Validation
+Validate fields in logical order so users get meaningful first-error feedback rather than random field validation failures.
+
+### Context-Aware Messages
+Include business context in custom error messages to help users understand why specific fields are required.
+
+### Field Focus Integration
+Custom validation procedures can integrate with page field focus to direct users to specific fields requiring attention.
+
+## Common Patterns
+
+### Validation Procedures
+Create dedicated validation procedures that use TestField internally but provide business-context error messages.
+
+### Status-Based Validation
+Use TestField with status checks to enforce business rules at specific workflow stages.
+
+### Cross-Table Validation
+Combine TestField with related table lookups to validate complex business relationships.
+

package/embedded-knowledge/domains/eva-errors/try-function-usage.md

@@ -0,0 +1,129 @@
+---
+title: "Try Function Usage Guidelines"
+domain: "eva-errors"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["try-function", "error-handling", "transactions", "external-systems", "best-practices"]
+samples: "samples/try-function-usage.md"
+related_topics:
+  - "codeunit-run-pattern.md"
+  - "testfield-error-handling.md"
+---
+# Try Function Usage Guidelines
+
+## Overview
+
+Try functions in Business Central provide a mechanism to catch runtime errors without terminating execution. While powerful, they have significant constraints around transaction handling that must be understood to use them correctly.
+
+**Core Principle**: Try functions are designed for error detection and graceful handling—not for suppressing errors during write operations.
+
+## When to Use Try Functions
+
+### External System Calls
+Try functions are ideal for wrapping calls to external systems where failures are expected and recoverable:
+- Web service calls that may timeout or fail
+- External API integrations
+- File system operations
+- HTTP client requests
+
+External systems are inherently unreliable, and wrapping these calls allows your code to detect failures and respond appropriately rather than crashing.
+
+### Validation Without Termination
+Use try functions when you need to validate data or test conditions without stopping execution:
+- Pre-flight checks before processing
+- Batch validation scenarios
+- User input validation with graceful feedback
+
+### Read-Only Operations
+Try functions work well for read operations that might fail:
+- Record lookups that may not find results
+- Configuration checks
+- Data existence verification
+
+## When NOT to Use Try Functions
+
+### Write Operations in the Call Stack
+**Critical Rule**: Never perform database write operations (INSERT, MODIFY, DELETE) inside a try function or any procedure called from within a try function.
+
+This is prohibited because:
+- The transaction behavior becomes unpredictable
+- Partial writes cannot be properly rolled back
+- Data integrity cannot be guaranteed
+- The AL runtime explicitly prevents this pattern
+
+### Suppressing Legitimate Errors
+Don't use try functions to hide errors that indicate real problems:
+- Business rule violations should be reported, not hidden
+- Data validation failures need user attention
+- Configuration errors require administrator action
+
+### Complex Transaction Scenarios
+Avoid try functions in the middle of multi-step transaction processes where you need consistent state management.
+
+## Transaction Behavior
+
+### Try Function Transaction Rules
+When a try function catches an error:
+- Any pending database changes within the try scope are rolled back
+- The calling code continues execution
+- GetLastErrorText() captures the error message
+
+### Write Operation Restrictions
+The Business Central runtime enforces that write transactions cannot occur within a try function's call stack. Attempting this will result in a runtime error indicating the operation is not allowed.
+
+## Implementation Patterns
+
+### External Service Wrapper
+Create try functions specifically for external calls, keeping all database operations outside:
+
+```
+// Correct pattern:
+1. Prepare data (outside try)
+2. Call try function for external operation
+3. Check result
+4. Write to database based on result (outside try)
+```
+
+### Error Detection and Logging
+Use try functions to detect errors, capture details, then handle the situation outside the try scope:
+
+```
+// Pattern:
+1. Call try function
+2. If failed: capture GetLastErrorText()
+3. Log error or notify user
+4. Take appropriate action
+```
+
+## Best Practices
+
+### Keep Try Functions Focused
+- Single responsibility: one external call or validation per try function
+- Minimal code inside the try function
+- No side effects beyond the intended operation
+
+### Handle Errors Appropriately
+- Always check the return value of try function calls
+- Use GetLastErrorText() to capture error details
+- Provide meaningful feedback or logging
+
+### Separate Concerns
+- Database operations: outside try functions
+- External calls: inside try functions
+- Error handling logic: after try function returns
+
+## Common Mistakes
+
+### Database Writes Inside Try
+Attempting to modify, insert, or delete records inside a try function or its call stack will fail at runtime.
+
+### Ignoring Return Values
+Calling a try function without checking its boolean return defeats the purpose of error handling.
+
+### Over-Reliance on Try Functions
+Using try functions as a general error suppression mechanism rather than for specific, expected failure scenarios creates fragile code.
+
+## Related Patterns
+
+For scenarios requiring transaction isolation with error handling, see the Codeunit.Run() pattern which provides proper transaction boundaries with error capture capabilities.
+