aspose-pdf · fahadadeel · Mar 27, 2026 · Mar 26, 2026
diff --git a/facades-annotations/add-annotation-verbose-logging.cs b/facades-annotations/add-annotation-verbose-logging.cs
@@ -0,0 +1,68 @@
+using System;
+using System.IO;
+using Aspose.Pdf;
+using Aspose.Pdf.Annotations;
+
+public class Program
+{
+    public static void Main(string[] args)
+    {
+        string inputPath = null;
+        string outputPath = null;
+        bool verbose = false;
+
+        foreach (string arg in args)
+        {
+            if (arg.Equals("--verbose", StringComparison.OrdinalIgnoreCase))
+            {
+                verbose = true;
+            }
+            else if (inputPath == null)
+            {
+                inputPath = arg;
+            }
+            else if (outputPath == null)
+            {
+                outputPath = arg;
+            }
+        }
+
+        if (string.IsNullOrEmpty(inputPath) || string.IsNullOrEmpty(outputPath))
+        {
+            Console.Error.WriteLine("Usage: program.exe <input.pdf> <output.pdf> [--verbose]");
+            return;
+        }
+
+        if (!File.Exists(inputPath))
+        {
+            Console.Error.WriteLine($"Input file not found: {inputPath}");
+            return;
+        }
+
+        try
+        {
+            using (Document doc = new Document(inputPath))
+            {
+                if (verbose)
+                {
+                    doc.EnableNotificationLogging = true;
+                }
+
+                Page page = doc.Pages[1];
+                Aspose.Pdf.Rectangle rect = new Aspose.Pdf.Rectangle(100, 500, 300, 550);
+                TextAnnotation annotation = new TextAnnotation(page, rect);
+                annotation.Title = "Verbose Example";
+                annotation.Contents = "Annotation added with verbose logging.";
+                page.Annotations.Add(annotation);
+
+                doc.Save(outputPath);
+            }
+
+            Console.WriteLine($"PDF saved to '{outputPath}'.");
+        }
+        catch (Exception ex)
+        {
+            Console.Error.WriteLine($"Error: {ex.Message}");
+        }
+    }
+}
diff --git a/facades-annotations/agents.md b/facades-annotations/agents.md
@@ -0,0 +1,175 @@
+---
+name: Facades - Annotations
+description: C# examples for Facades - Annotations using Aspose.PDF for .NET
+language: csharp
+framework: net10.0
+parent: ../agents.md
+---
+
+# AGENTS - Facades - Annotations
+
+## Persona
+
+You are a C# developer specializing in PDF processing using Aspose.PDF for .NET,
+working within the **Facades - Annotations** category.
+This folder contains standalone C# examples for Facades - Annotations operations.
+See the root [agents.md](../agents.md) for repository-wide conventions and boundaries.
+
+## Scope
+- This folder contains examples for **Facades - Annotations**.
+- Files are standalone `.cs` examples stored directly in this folder.
+
+## Files in this folder
+- [add-annotation-verbose-logging](./add-annotation-verbose-logging.cs)
+- [annotation-count-per-page](./annotation-count-per-page.cs)
+- [annotation-performance-logger](./annotation-performance-logger.cs)
+- [annotation-summary-report](./annotation-summary-report.cs)
+- [async-delete-annotations](./async-delete-annotations.cs)
+- [backup-before-flattening](./backup-before-flattening.cs)
+- [batch-annotation-flattening-cancel](./batch-annotation-flattening-cancel.cs)
+- [batch-delete-annotations-progress](./batch-delete-annotations-progress.cs)
+- [batch-delete-annotations-report](./batch-delete-annotations-report.cs)
+- [batch-delete-annotations-retain](./batch-delete-annotations-retain.cs)
+- [batch-delete-stamp-annotations](./batch-delete-stamp-annotations.cs)
+- [batch-import-xfdf-annotations](./batch-import-xfdf-annotations.cs)
+- [batch-process-azure-pdf](./batch-process-azure-pdf.cs)
+- [batch-update-annotation-author](./batch-update-annotation-author.cs)
+- [benchmark-delete-annotations](./benchmark-delete-annotations.cs)
+- [check-duplicate-annotation-names](./check-duplicate-annotation-names.cs)
+- [clone-annotation-change-color](./clone-annotation-change-color.cs)
+- [clone-modify-annotation](./clone-modify-annotation.cs)
+- [compare-annotation-counts](./compare-annotation-counts.cs)
+- [concurrent-import-delete](./concurrent-import-delete.cs)
+- [copy-annotations-template-to-multiple](./copy-annotations-template-to-multiple.cs)
+- [count-pdf-annotation-types](./count-pdf-annotation-types.cs)
+- [delete-all-annotations](./delete-all-annotations.cs)
+- [delete-annotation-by-name](./delete-annotation-by-name.cs)
+- [delete-annotation-by-name__v2](./delete-annotation-by-name__v2.cs)
+- [delete-annotation-error-handling](./delete-annotation-error-handling.cs)
+- [delete-annotations-by-author](./delete-annotations-by-author.cs)
+- [delete-annotations-by-color](./delete-annotations-by-color.cs)
+- [delete-annotations-by-name](./delete-annotations-by-name.cs)
+- [delete-annotations-export-xfdf](./delete-annotations-export-xfdf.cs)
+- [delete-annotations-folder](./delete-annotations-folder.cs)
+- [delete-annotations-from-config](./delete-annotations-from-config.cs)
+- [delete-annotations-parallel](./delete-annotations-parallel.cs)
+- [delete-annotations-unit-test](./delete-annotations-unit-test.cs)
+- [delete-annotations-with-backup](./delete-annotations-with-backup.cs)
+- [delete-annotations-with-logging](./delete-annotations-with-logging.cs)
+- [delete-flatten-annotations](./delete-flatten-annotations.cs)
+- [delete-pdf-annotation-retry](./delete-pdf-annotation-retry.cs)
+- [delete-pdf-annotations](./delete-pdf-annotations.cs)
+- [delete-text-annotations](./delete-text-annotations.cs)
+- [diagnostic-annotation-workflow](./diagnostic-annotation-workflow.cs)
+- [export-annotations-empty-pdf](./export-annotations-empty-pdf.cs)
+- [export-annotations-pretty-xfdf](./export-annotations-pretty-xfdf.cs)
+- [export-annotations-unbound-test](./export-annotations-unbound-test.cs)
+- [export-annotations-xfdf-custom-namespace](./export-annotations-xfdf-custom-namespace.cs)
+- [export-annotations-xfdf-gzip](./export-annotations-xfdf-gzip.cs)
+- [export-annotations-xfdf-log](./export-annotations-xfdf-log.cs)
+- [export-annotations-xfdf](./export-annotations-xfdf.cs)
+- [export-delete-archive-annotations](./export-delete-archive-annotations.cs)
+- [export-highlight-annotations](./export-highlight-annotations.cs)
+- [export-import-annotations-xfdf](./export-import-annotations-xfdf.cs)
+- [export-pdf-annotations-json](./export-pdf-annotations-json.cs)
+- [export-pdf-annotations-xfdf](./export-pdf-annotations-xfdf.cs)
+- [export-pdf-annotations-xfdf__v2](./export-pdf-annotations-xfdf__v2.cs)
+- [extract-annotation-authors](./extract-annotation-authors.cs)
+- [extract-annotation-details](./extract-annotation-details.cs)
+- [extract-annotation-rectangles](./extract-annotation-rectangles.cs)
+- [extract-annotation-summary](./extract-annotation-summary.cs)
+- [flatten-annotations-first-five-pages](./flatten-annotations-first-five-pages.cs)
+- [flatten-annotations-log-sizes](./flatten-annotations-log-sizes.cs)
+- [flatten-annotations-verify](./flatten-annotations-verify.cs)
+- [flatten-pdf-add-metadata](./flatten-pdf-add-metadata.cs)
+- [flatten-pdf-annotations-nightly](./flatten-pdf-annotations-nightly.cs)
+- [flatten-pdf-annotations](./flatten-pdf-annotations.cs)
+- [flatten-pdf-annotations__v2](./flatten-pdf-annotations__v2.cs)
+- [flatten-pdf-annotations__v3](./flatten-pdf-annotations__v3.cs)
+- [flatten-pdf-annotations__v4](./flatten-pdf-annotations__v4.cs)
+- [flatten-pdf-custom-output](./flatten-pdf-custom-output.cs)
+- [folder-monitor-flatten-pdf-annotations](./folder-monitor-flatten-pdf-annotations.cs)
+- [get-annotation-names-by-author](./get-annotation-names-by-author.cs)
+- [import-annotations-no-overwrite](./import-annotations-no-overwrite.cs)
+- [import-annotations-xfdf](./import-annotations-xfdf.cs)
+- [import-xfdf-and-cleanup](./import-xfdf-and-cleanup.cs)
+- [import-xfdf-annotations](./import-xfdf-annotations.cs)
+- [import-xfdf-annotations__v2](./import-xfdf-annotations__v2.cs)
+- [import-xfdf-into-multiple-pdfs](./import-xfdf-into-multiple-pdfs.cs)
+- [list-annotation-names](./list-annotation-names.cs)
+- [list-annotations-csv](./list-annotations-csv.cs)
+- [log-annotation-modification](./log-annotation-modification.cs)
+- [measure-flatten-annotations](./measure-flatten-annotations.cs)
+- [merge-annotations](./merge-annotations.cs)
+- [merge-xfdf-files](./merge-xfdf-files.cs)
+- [modify-annotation-author](./modify-annotation-author.cs)
+- [modify-annotation-flags](./modify-annotation-flags.cs)
+- [modify-annotation-subject-color](./modify-annotation-subject-color.cs)
+- [modifyannotations-subject-test](./modifyannotations-subject-test.cs)
+- [pdf-annotation-helper](./pdf-annotation-helper.cs)
+- [pdf-utility-cli](./pdf-utility-cli.cs)
+- [pdfannotation-editor-wrapper](./pdfannotation-editor-wrapper.cs)
+- [pdfannotationeditor-health-check](./pdfannotationeditor-health-check.cs)
+- [preserve-annotation-appearance](./preserve-annotation-appearance.cs)
+- [remove-all-annotations](./remove-all-annotations.cs)
+- [remove-link-annotations](./remove-link-annotations.cs)
+- [remove-old-annotations](./remove-old-annotations.cs)
+- [remove-pdf-annotations](./remove-pdf-annotations.cs)
+- [rename-annotation-names](./rename-annotation-names.cs)
+- [retry-annotation-modification](./retry-annotation-modification.cs)
+- [safeguard-flattening-signatures](./safeguard-flattening-signatures.cs)
+- [set-annotations-open](./set-annotations-open.cs)
+- [set-readonly-annotation](./set-readonly-annotation.cs)
+- [skip-flatten-readonly-annotations](./skip-flatten-readonly-annotations.cs)
+- [update-annotation-modified-date](./update-annotation-modified-date.cs)
+- [validate-no-annotations-after-flattening](./validate-no-annotations-after-flattening.cs)
+- [validate-pdf-integrity](./validate-pdf-integrity.cs)
+- [validate-xfdf](./validate-xfdf.cs)
+
+## Category Statistics
+- Total examples: 105
+
+## Category-Specific Tips
+
+### Key API Surface
+- `Aspose.Pdf.Annotations.AnnotationType`
+- `Aspose.Pdf.Facades.AutoFiller`
+- `Aspose.Pdf.Facades.AutoFiller.BindPdf`
+- `Aspose.Pdf.Facades.AutoFiller.Close`
+- `Aspose.Pdf.Facades.AutoFiller.Dispose`
+- `Aspose.Pdf.Facades.AutoFiller.ImportDataTable`
+- `Aspose.Pdf.Facades.AutoFiller.InputFileName`
+- `Aspose.Pdf.Facades.AutoFiller.InputStream`
+- `Aspose.Pdf.Facades.AutoFiller.OutputStream`
+- `Aspose.Pdf.Facades.AutoFiller.OutputStreams`
+- `Aspose.Pdf.Facades.AutoFiller.Save`
+- `Aspose.Pdf.Facades.AutoFiller.UnFlattenFields`
+- `Aspose.Pdf.Facades.BDCProperties`
+- `Aspose.Pdf.Facades.BDCProperties.E`
+- `Aspose.Pdf.Facades.BDCProperties.Lang`
+
+### Rules
+- Instantiate Aspose.Pdf.Facades.PdfContentEditor, bind the source PDF via BindPdf({input_pdf}), then call CreateFileAttachment({rect}, {string_literal}, {string_literal}, {int}, {string_literal}, {float}) where the parameters are the annotation rectangle, description, attached file path, page number, icon name, and icon transparency.
+- After adding the annotation, persist the changes by invoking Save({output_pdf}) on the same PdfContentEditor instance.
+- To delete all annotations: instantiate {class:PdfAnnotationEditor}, call BindPdf({input_pdf}), invoke DeleteAnnotations(), then Save({output_pdf}).
+- PdfAnnotationEditor must be bound to a PDF via BindPdf before any annotation‑related methods (e.g., DeleteAnnotations) can be used.
+- Bind a PDF file ({input_pdf}) to a PdfAnnotationEditor instance using BindPdf before any annotation operations.
+
+### Warnings
+- The example uses System.Drawing.Rectangle for the annotation bounds, which requires a reference to System.Drawing.Common on non‑Windows platforms.
+- Transparency support may depend on the chosen icon and PDF viewer.
+- The example does not use a using statement for FileStream; callers should ensure proper disposal.
+- Only FreeText and Line annotation types are shown; other types can be included by adding their string names to the array.
+- AutoFiller is in the Facades namespace — add 'using Aspose.Pdf.Facades;' explicitly.
+
+## General Tips
+- See parent [agents.md](../agents.md) for:
+  - **Boundaries** — Always / Ask First / Never rules for all examples
+  - **Common Mistakes** — verified anti-patterns that cause build failures
+  - **Domain Knowledge** — cross-cutting API-specific gotchas
+  - **Testing Guide** — build and run verification steps
+- Review code examples in this folder for Facades - Annotations patterns
+
+<!-- AUTOGENERATED:START -->
+Updated: 2026-03-27 | Run: `20260327_002039_d7a850`
+<!-- AUTOGENERATED:END -->
diff --git a/facades-annotations/annotation-count-per-page.cs b/facades-annotations/annotation-count-per-page.cs
@@ -0,0 +1,30 @@
+using System;
+using System.IO;
+using Aspose.Pdf;
+
+class Program
+{
+    static void Main()
+    {
+        const string inputPath = "input.pdf";
+
+        if (!File.Exists(inputPath))
+        {
+            Console.Error.WriteLine($"File not found: {inputPath}");
+            return;
+        }
+
+        using (Document doc = new Document(inputPath))
+        {
+            int pageCount = doc.Pages.Count;
+            Console.WriteLine($"Document has {pageCount} page(s).");
+
+            for (int i = 1; i <= pageCount; i++)
+            {
+                Page page = doc.Pages[i];
+                int annotationCount = page.Annotations.Count;
+                Console.WriteLine($"Page {i}: {annotationCount} annotation(s)");
+            }
+        }
+    }
+}
diff --git a/facades-annotations/annotation-performance-logger.cs b/facades-annotations/annotation-performance-logger.cs
@@ -0,0 +1,51 @@
+using System;
+using System.IO;
+using System.Diagnostics;
+using Aspose.Pdf;
+using Aspose.Pdf.Annotations;
+
+public class AnnotationPerformanceLogger
+{
+    public static void Main()
+    {
+        const string inputPath = "input.pdf";
+        const string outputPath = "output.pdf";
+
+        if (!File.Exists(inputPath))
+        {
+            Console.Error.WriteLine($"File not found: {inputPath}");
+            return;
+        }
+
+        using (Document doc = new Document(inputPath))
+        {
+            // Iterate through all pages (1‑based indexing)
+            for (int i = 1; i <= doc.Pages.Count; i++)
+            {
+                Page page = doc.Pages[i];
+
+                // ----- Add a TextAnnotation and measure duration -----
+                Stopwatch addTimer = Stopwatch.StartNew();
+                Aspose.Pdf.Rectangle rect = new Aspose.Pdf.Rectangle(100, 500, 300, 550);
+                TextAnnotation textAnn = new TextAnnotation(page, rect);
+                textAnn.Title = "Note";
+                textAnn.Contents = $"Added on page {i}";
+                textAnn.Color = Aspose.Pdf.Color.Yellow;
+                page.Annotations.Add(textAnn);
+                addTimer.Stop();
+                Console.WriteLine($"Add TextAnnotation on page {i} took {addTimer.ElapsedMilliseconds} ms");
+
+                // ----- Delete the just‑added annotation and measure duration -----
+                Stopwatch deleteTimer = Stopwatch.StartNew();
+                // Annotations collection uses 1‑based indexing as well
+                page.Annotations.Delete(page.Annotations.Count);
+                deleteTimer.Stop();
+                Console.WriteLine($"Delete last annotation on page {i} took {deleteTimer.ElapsedMilliseconds} ms");
+            }
+
+            doc.Save(outputPath);
+        }
+
+        Console.WriteLine($"Processed PDF saved as '{outputPath}'.");
+    }
+}