Merge branch 'release/26.3.0' into examples/9f94b342-parse-pdf

Author: fahadadeel

.github/workflows/validate-pr.yml

@@ -60,20 +60,76 @@ jobs:
           dotnet restore .build-template/ --verbosity quiet
           echo "Template ready with Aspose.PDF ${{ steps.version.outputs.nuget_version }}"
 
-      # ── Find .cs files changed in this PR ──
-      # Use merge-base (three-dot diff) so we only see files the PR itself
-      # changed — not files brought in from the base branch when the PR is
-      # updated via "Update branch" (which merges base into head).
+      # ── Find .cs files to validate ──
+      # We apply up to three filters to avoid re-running CI on files that
+      # didn't actually change:
+      #   1. PR-owned filter (merge-base): only files the PR itself added
+      #      or modified vs the base branch — skips files that came in via
+      #      "Update branch" merges from the base.
+      #   2. Incremental filter: if HEAD is a merge commit (i.e. the user
+      #      clicked "Update branch"), only validate files that changed in
+      #      the merge itself (HEAD^1..HEAD). If the merge introduced no
+      #      new changes to PR-owned .cs files, skip the build entirely.
+      #   3. Environment tripwire: if the merge touched csproj, workflow,
+      #      index.json, or global.json, force a full revalidation because
+      #      the build environment may have changed.
       - name: Get changed .cs files
         id: changed
         run: |
           BASE="${{ github.event.pull_request.base.sha }}"
           HEAD="${{ github.event.pull_request.head.sha }}"
           MERGE_BASE=$(git merge-base "$BASE" "$HEAD")
-          echo "PR base:   $BASE"
-          echo "PR head:   $HEAD"
+          echo "PR base:    $BASE"
+          echo "PR head:    $HEAD"
           echo "Merge base: $MERGE_BASE"
-          FILES=$(git diff --name-only "$MERGE_BASE" "$HEAD" -- '*.cs' | grep '\.cs$' || true)
+
+          # ── Filter 1: files the PR itself changed ──
+          PR_FILES=$(git diff --name-only "$MERGE_BASE" "$HEAD" -- '*.cs' | grep '\.cs$' || true)
+
+          # ── Is HEAD a merge commit (i.e. "Update branch" was clicked)? ──
+          IS_MERGE=false
+          if git rev-parse --verify HEAD^2 >/dev/null 2>&1; then
+            IS_MERGE=true
+            echo "HEAD is a merge commit (Update branch was used)"
+          fi
+
+          # ── Filter 3: environment tripwire (forces full revalidate) ──
+          FORCE_FULL=false
+          if [ "$IS_MERGE" = "true" ]; then
+            ENV_DIFF=$(git diff --name-only HEAD^1 HEAD -- \
+              'index.json' \
+              '.github/workflows/validate-pr.yml' \
+              '**/*.csproj' \
+              'global.json' 2>/dev/null || true)
+            if [ -n "$ENV_DIFF" ]; then
+              FORCE_FULL=true
+              echo "Environment changed in merge — forcing full revalidation:"
+              echo "$ENV_DIFF"
+            fi
+          fi
+
+          # ── Filter 2: incremental (only files touched by the merge) ──
+          if [ "$IS_MERGE" = "true" ] && [ "$FORCE_FULL" = "false" ]; then
+            RECENT_FILES=$(git diff --name-only HEAD^1 HEAD -- '*.cs' | grep '\.cs$' || true)
+            if [ -z "$RECENT_FILES" ]; then
+              echo "Merge did not touch any .cs files — skipping validation."
+              echo "has_cs=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            # Intersect PR-owned files with files touched by the merge
+            FILES=$(comm -12 \
+              <(printf '%s\n' "$PR_FILES" | sort -u) \
+              <(printf '%s\n' "$RECENT_FILES" | sort -u))
+            if [ -z "$FILES" ]; then
+              echo "Merge touched .cs files but none were PR-owned — skipping validation."
+              echo "has_cs=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            echo "Incremental mode: validating only files touched by the merge"
+          else
+            FILES="$PR_FILES"
+          fi
+
           if [ -z "$FILES" ]; then
             echo "No .cs files changed in this PR"
             echo "has_cs=false" >> "$GITHUB_OUTPUT"

facades-annotations/add-annotation-verbose-logging.cs

@@ -0,0 +1,54 @@
+using System;
+using System.IO;
+using Aspose.Pdf;
+using Aspose.Pdf.Facades;
+using Aspose.Pdf.Annotations;
+
+class Program
+{
+    static void Main()
+    {
+        const string inputPath = "input.pdf";
+        const string outputPath = "output_modified.pdf";
+
+        if (!File.Exists(inputPath))
+        {
+            Console.Error.WriteLine($"File not found: {inputPath}");
+            return;
+        }
+
+        // Load the PDF document (lifecycle rule: use using for deterministic disposal)
+        using (Document doc = new Document(inputPath))
+        {
+            // Prepare a concrete annotation (TextAnnotation) using the (Page, Rectangle) constructor
+            // This is required because TextAnnotation does not expose a public parameter‑less constructor.
+            Page firstPage = doc.Pages[1];
+            Aspose.Pdf.Rectangle rect = new Aspose.Pdf.Rectangle(100, 500, 300, 550);
+            TextAnnotation customAnnot = new TextAnnotation(firstPage, rect)
+            {
+                Title = "Custom Flag",
+                Contents = "Annotation with custom flags",
+                Color = Aspose.Pdf.Color.Yellow,
+                // Combine desired flags (e.g., Print and Locked)
+                Flags = AnnotationFlags.Print | AnnotationFlags.Locked
+            };
+
+            // Initialize the annotation editor facade
+            using (PdfAnnotationEditor editor = new PdfAnnotationEditor())
+            {
+                // Bind the document to the editor
+                editor.BindPdf(doc);
+
+                // Modify annotations on the desired page range (1‑based indexing)
+                int startPage = 1;
+                int endPage = doc.Pages.Count;
+                editor.ModifyAnnotations(startPage, endPage, customAnnot);
+
+                // Save the modified PDF (lifecycle rule: use provided Save method)
+                editor.Save(outputPath);
+            }
+        }
+
+        Console.WriteLine($"Modified PDF saved to '{outputPath}'.");
+    }
+}

facades-annotations/add-custom-annotation-flags.cs

@@ -0,0 +1,81 @@
+using System;
+using System.IO;
+using Aspose.Pdf;
+using Aspose.Pdf.Annotations;
+using Aspose.Pdf.Facades;
+
+class Program
+{
+    static void Main()
+    {
+        const string inputPath  = "input.pdf";
+        const string outputPath = "output_custom_meta.pdf";
+
+        if (!File.Exists(inputPath))
+        {
+            Console.Error.WriteLine($"File not found: {inputPath}");
+            return;
+        }
+
+        // Load the PDF document
+        using (Document doc = new Document(inputPath))
+        {
+            // -----------------------------------------------------------------
+            // 1. Add a sample annotation (TextAnnotation) to demonstrate custom
+            //    metadata injection.
+            // -----------------------------------------------------------------
+            Page page = doc.Pages[1];
+            // Fully qualified rectangle to avoid ambiguity with System.Drawing
+            Aspose.Pdf.Rectangle rect = new Aspose.Pdf.Rectangle(100, 500, 300, 550);
+            TextAnnotation txtAnn = new TextAnnotation(page, rect)
+            {
+                Title    = "Sample Note",
+                Contents = "This annotation will carry custom metadata.",
+                Color    = Aspose.Pdf.Color.Yellow,
+                Open     = true
+            };
+            page.Annotations.Add(txtAnn);
+
+            // -----------------------------------------------------------------
+            // 2. Use PdfAnnotationEditor (Facades API) to modify the annotation.
+            //    Since the Facades API only supports a limited set of fields,
+            //    we embed custom key/value pairs into the 'Subject' property as
+            //    a JSON string. This effectively extends the annotation dictionary.
+            // -----------------------------------------------------------------
+            using (PdfAnnotationEditor editor = new PdfAnnotationEditor())
+            {
+                // Bind the same document instance to the editor
+                editor.BindPdf(doc);
+
+                // Prepare custom metadata (key/value) as JSON
+                string customMetaJson = "{\"CustomKey\":\"CustomValue\",\"Author\":\"John Doe\"}";
+
+                // Modify annotations on page 1 (page indexes are 1‑based)
+                // Parameters: startPage, endPage, Annotation object with modified fields
+                // Only the fields listed in ModifyAnnotations are respected.
+                // We set the Subject field to carry our custom metadata.
+                txtAnn.Subject = customMetaJson; // Subject will hold the JSON payload
+
+                // Apply the modification
+                editor.ModifyAnnotations(1, 1, txtAnn);
+            }
+
+            // -----------------------------------------------------------------
+            // 3. (Optional) Add a document‑level custom property using PdfFileInfo.
+            //    This demonstrates how to store additional metadata at the file level.
+            // -----------------------------------------------------------------
+            using (PdfFileInfo fileInfo = new PdfFileInfo())
+            {
+                fileInfo.BindPdf(doc);
+                fileInfo.SetMetaInfo("DocumentCustomKey", "DocumentCustomValue");
+                // No need to call SaveNewInfo; the changes are persisted when the
+                // underlying Document is saved.
+            }
+
+            // Save the modified PDF
+            doc.Save(outputPath);
+        }
+
+        Console.WriteLine($"PDF saved with custom annotation metadata to '{outputPath}'.");
+    }
+}