[AUTO] Document Properties Examples Update

document-properties/add-a-custom-property-containing-an-array-of-string-tags-to-categorize-workbook-content.cs

@@ -0,0 +1,24 @@
+using System;
+using Aspose.Cells;
+using Aspose.Cells.Properties;
+
+class Program
+{
+    static void Main()
+    {
+        // Create a new workbook
+        Workbook workbook = new Workbook();
+
+        // Define an array of tags to categorize the workbook content
+        string[] tags = new string[] { "Finance", "Quarterly", "Confidential" };
+
+        // Convert the string array to a single string (comma‑separated) for storage
+        string tagsValue = string.Join(",", tags);
+
+        // Add a custom document property named "Tags" with the serialized array value
+        workbook.CustomDocumentProperties.Add("Tags", tagsValue);
+
+        // Save the workbook to a file
+        workbook.Save("WorkbookWithTags.xlsx");
+    }
+}

document-properties/agents.md

@@ -0,0 +1,111 @@
+---
+category: document-properties
+framework: .NET
+parent: ../agents.md
+version: v2
+---
+
+# Persona
+
+You are a C# developer specializing in document properties and metadata management using Aspose.Cells for .NET.
+
+Generate simple, correct, production-quality examples that demonstrate ONE document-properties scenario at a time.
+
+---
+
+# Scope
+
+- Standalone .cs examples
+- One operation per example
+- Fully runnable with dotnet run
+- No external dependencies
+
+---
+
+# Required Namespaces
+
+using System;
+using Aspose.Cells;
+
+---
+
+# Key APIs
+
+- BuiltInDocumentPropertyCollection
+- CustomDocumentPropertyCollection
+- Workbook.BuiltInDocumentProperties
+- Workbook.CustomDocumentProperties
+
+---
+
+# Common Pattern
+
+1. Create workbook
+2. Access document properties
+3. Add, read, update, or remove properties
+4. Save workbook
+5. Print success message
+
+---
+
+# Document Properties Rules
+
+- Use BuiltInDocumentProperties for standard metadata
+- Use CustomDocumentProperties for user-defined metadata
+- Use correct property data types
+- One example = one document-properties operation
+
+---
+
+# Input Strategy
+
+- Do NOT rely on external XLSX files
+- Create workbook programmatically
+- Keep examples self-contained
+
+---
+
+# Output Rules
+
+- Always generate output.xlsx
+- Ensure workbook is saved successfully
+- Output files are written to the working directory
+
+---
+
+# Common Tasks
+
+- Read built-in properties
+- Add custom property
+- Update property value
+- Remove property
+- Enumerate document properties
+
+---
+
+# Common Mistakes
+
+❌ var workbook = new Workbook();
+✅ Workbook workbook = new Workbook();
+
+❌ Store all values as strings
+✅ Use appropriate property types
+
+❌ Workbook workbook = new Workbook("input.xlsx");
+✅ Workbook workbook = new Workbook();
+
+---
+
+# Code Simplicity
+
+- Keep examples concise
+- Avoid unnecessary abstractions
+
+---
+
+# General Rules
+
+Refer to the root agents.md for:
+- Boundaries
+- Testing requirements
+- Build and run instructions

document-properties/batch-process-all-workbooks-in-a-folder-setting-each-files-language-property-to-en-gb.cs

@@ -0,0 +1,63 @@
+using System;
+using System.IO;
+using Aspose.Cells;
+
+namespace BatchSetLanguageApp
+{
+    class BatchSetLanguage
+    {
+        static void Main()
+        {
+            try
+            {
+                // Folder containing the workbooks to process
+                string folderPath = @"C:\Path\To\Folder";
+
+                // Verify folder exists
+                if (!Directory.Exists(folderPath))
+                {
+                    Console.WriteLine($"Folder not found: {folderPath}");
+                    return;
+                }
+
+                // Retrieve all files in the folder
+                string[] allFiles = Directory.GetFiles(folderPath, "*.*", SearchOption.TopDirectoryOnly);
+
+                foreach (string filePath in allFiles)
+                {
+                    try
+                    {
+                        // Process only supported Excel formats
+                        string ext = Path.GetExtension(filePath).ToLowerInvariant();
+                        if (ext != ".xls" && ext != ".xlsx" && ext != ".xlsm" && ext != ".xlsb" && ext != ".csv")
+                            continue;
+
+                        // Ensure the file exists before loading
+                        if (!File.Exists(filePath))
+                        {
+                            Console.WriteLine($"File not found: {filePath}");
+                            continue;
+                        }
+
+                        // Load the workbook (lifecycle rule: load)
+                        Workbook workbook = new Workbook(filePath);
+
+                        // Set the built‑in document property "Language" to "en-GB"
+                        workbook.BuiltInDocumentProperties.Language = "en-GB";
+
+                        // Save the workbook back to the same file (lifecycle rule: save)
+                        workbook.Save(filePath);
+                    }
+                    catch (Exception ex)
+                    {
+                        Console.WriteLine($"Error processing '{filePath}': {ex.Message}");
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                Console.WriteLine($"Unexpected error: {ex.Message}");
+            }
+        }
+    }
+}

document-properties/compare-custom-property-sets-between-two-workbooks-and-generate-a-list-of-differences-for-auditing.cs

@@ -0,0 +1,73 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Aspose.Cells;
+using Aspose.Cells.Properties;
+
+class Program
+{
+    static void Main()
+    {
+        // Paths to the two workbooks to compare
+        string workbookPath1 = "Workbook1.xlsx";
+        string workbookPath2 = "Workbook2.xlsx";
+
+        // Load the workbooks (uses the Workbook(string) constructor)
+        Workbook wb1 = new Workbook(workbookPath1);
+        Workbook wb2 = new Workbook(workbookPath2);
+
+        // Retrieve the custom document property collections
+        CustomDocumentPropertyCollection props1 = wb1.CustomDocumentProperties;
+        CustomDocumentPropertyCollection props2 = wb2.CustomDocumentProperties;
+
+        // Prepare a list to hold audit messages
+        List<string> differences = new List<string>();
+
+        // Helper: create a dictionary for quick lookup of properties by name
+        var dict2 = new Dictionary<string, DocumentProperty>(StringComparer.OrdinalIgnoreCase);
+        foreach (DocumentProperty p in props2)
+        {
+            dict2[p.Name] = p;
+        }
+
+        // Check for removed or modified properties
+        foreach (DocumentProperty p1 in props1)
+        {
+            if (!dict2.TryGetValue(p1.Name, out DocumentProperty p2))
+            {
+                differences.Add($"Removed: '{p1.Name}' with value '{p1.Value}'");
+            }
+            else
+            {
+                // Compare values (null‑safe)
+                string val1 = p1.Value?.ToString() ?? string.Empty;
+                string val2 = p2.Value?.ToString() ?? string.Empty;
+                if (!val1.Equals(val2, StringComparison.Ordinal))
+                {
+                    differences.Add($"Modified: '{p1.Name}' changed from '{val1}' to '{val2}'");
+                }
+                // Remove the entry so that later we can detect additions
+                dict2.Remove(p1.Name);
+            }
+        }
+
+        // Remaining entries in dict2 are properties that exist only in workbook2 (added)
+        foreach (var kvp in dict2)
+        {
+            DocumentProperty p = kvp.Value;
+            differences.Add($"Added: '{p.Name}' with value '{p.Value}'");
+        }
+
+        // Output the differences to console
+        Console.WriteLine("Custom Document Property Differences:");
+        foreach (string diff in differences)
+        {
+            Console.WriteLine(diff);
+        }
+
+        // Optionally, write the audit report to a text file
+        string reportPath = "CustomPropertiesAudit.txt";
+        File.WriteAllLines(reportPath, differences);
+        Console.WriteLine($"Audit report saved to: {reportPath}");
+    }
+}

document-properties/create-a-unit-test-that-adds-a-custom-property-saves-the-workbook-reloads-it-and-verifies-persistence.cs

@@ -0,0 +1,81 @@
+using System;
+using System.IO;
+using System.Linq;
+using Aspose.Cells;
+using Aspose.Cells.Properties;
+
+namespace AsposeCellsTests
+{
+    public class CustomPropertyPersistenceTests
+    {
+        public void Run()
+        {
+            // Arrange: create a workbook and add a custom property
+            Workbook workbook = new Workbook();
+            Worksheet sheet = workbook.Worksheets[0];
+            const string propertyName = "TestProp";
+            const string propertyValue = "TestValue";
+            sheet.CustomProperties.Add(propertyName, propertyValue);
+
+            // Temporary file for saving the workbook
+            string tempFile = Path.Combine(Path.GetTempPath(), $"CustomProp_{Guid.NewGuid()}.xlsx");
+
+            try
+            {
+                // Act: save the workbook
+                workbook.Save(tempFile);
+
+                // Ensure the file exists before loading
+                if (!File.Exists(tempFile))
+                    throw new FileNotFoundException("Saved workbook not found.", tempFile);
+
+                // Load the workbook back
+                Workbook loadedWorkbook = new Workbook(tempFile);
+                Worksheet loadedSheet = loadedWorkbook.Worksheets[0];
+
+                // Retrieve the custom property
+                CustomProperty loadedProperty = loadedSheet.CustomProperties
+                    .FirstOrDefault(p => p.Name == propertyName);
+
+                // Assert: property exists and value matches
+                if (loadedProperty == null)
+                    throw new InvalidOperationException("Custom property was not found after loading the workbook.");
+
+                if (!propertyValue.Equals(loadedProperty.Value?.ToString()))
+                    throw new InvalidOperationException("Custom property value did not persist correctly.");
+
+                Console.WriteLine("Custom property persisted successfully.");
+            }
+            catch (Exception ex)
+            {
+                // Runtime safety: log and rethrow
+                Console.WriteLine($"Error: {ex.Message}");
+                throw;
+            }
+            finally
+            {
+                // Cleanup: delete temporary file if it exists
+                if (File.Exists(tempFile))
+                {
+                    try { File.Delete(tempFile); } catch { /* ignore cleanup errors */ }
+                }
+            }
+        }
+    }
+
+    class Program
+    {
+        static void Main()
+        {
+            try
+            {
+                var test = new CustomPropertyPersistenceTests();
+                test.Run();
+            }
+            catch (Exception ex)
+            {
+                Console.WriteLine($"Test failed: {ex.Message}");
+            }
+        }
+    }
+}