Work with document metadata Leave feedback

Document metadata is the data a document keeps about itself. It travels inside the file but stays invisible when the document is opened in a viewer or editor: readers see the pages, while the metadata layer quietly records who made the file, when, with which tool, and anything else an application decided to store there.

Metadata entries usually fall into three classic categories:

• Descriptive — what the document is about: title, author, subject, keywords, comments. This is what search engines and document management systems index first.
• Structural — how the file is built: format and version, page count and dimensions, relationships between embedded parts.
• Administrative — how the file is managed: creation and modification dates, producing application, revision history, rights and permissions.

Each document family keeps this layer in its own physical location, and GroupDocs.Signature mirrors those locations with dedicated classes derived from MetadataSignature:

Every entry, whatever the format, is a name-value pair with a detected value type. The MetadataSignature base class exposes the Name, Value and Type properties, where Type is one of the MetadataType values: Boolean, Integer, Double, DateTime, String or Undefined.

Well-maintained metadata is what makes large document collections manageable. Files with meaningful descriptive entries can be found by a property query instead of a full-text scan, routed automatically to the right storage or workflow branch, and grouped with their related revisions. Because GroupDocs.Signature treats metadata entries as invisible electronic signatures, the same layer becomes an audit-trail channel: you can stamp a document with signer identity, document identifiers, timestamps or whole serialized business objects without changing a single pixel of its visible content.

The same invisibility is also a risk. Documents leave organizations carrying author names, internal file paths, tracked-changes leftovers and other details nobody intended to publish, which can violate privacy rules or leak internal information. Before distributing a document it is worth auditing what its metadata layer actually contains — the search and document-information APIs described below enumerate that layer in a few lines of code, and the encryption features let you protect the values you add deliberately.

Format notes to keep in mind:

• PDF metadata operations target the XMP packet only. Entries are read from and written to the document’s XMP metadata; each entry name may carry a tag prefix (xmp, dc, pdf and others) controlled via PdfMetadataSignature.TagPrefix. The predefined PdfMetadataSignatures class offers ready-made standard entries such as Author, CreateDate or Producer.
• Image metadata is written as EXIF property items. If the loaded image contains no EXIF entries at all — which is typical for freshly created PNG, BMP or GIF files — the metadata signing step is skipped silently, without an error. Formats such as JPG or TIFF that normally carry EXIF data are the reliable targets. SVG, CDR, CMX, WEBP and WMF images do not support metadata at all, and DICOM images cannot be signed through MetadataSignOptions.
• Built-in document properties are excluded by default. GetDocumentInfo returns them only when SignatureSettings.IncludeStandardMetadataSignatures is set to true, and Search returns them only when MetadataSearchOptions.IncludeBuiltinProperties is enabled — the latter applies to Word processing, Spreadsheet and Presentation documents.

The complete per-format feature matrix is available on the supported document formats page.

Warning

Metadata signatures support the add (sign) and search operations only. The Update, Delete and Verify methods do not process metadata signatures — there is no way to modify, remove or verify a metadata entry through those APIs. To change an existing entry, sign the document again with the same metadata name: the new value replaces the previous one.

The Signature class method GetDocumentInfo returns general document details together with the collection of metadata entries found in the file:

string filePath = "sample.docx";

// Built-in properties (author, creation date, etc.) are excluded by default.
// Turn them on via SignatureSettings to see the complete metadata picture.
SignatureSettings signatureSettings = new SignatureSettings()
{
    IncludeStandardMetadataSignatures = true
};

using (Signature signature = new Signature(filePath, signatureSettings))
{
    IDocumentInfo documentInfo = signature.GetDocumentInfo();
    Console.WriteLine($"Document properties {Path.GetFileName(filePath)}:");
    Console.WriteLine($" - format : {documentInfo.FileType.FileFormat}");
    Console.WriteLine($" - extension : {documentInfo.FileType.Extension}");
    Console.WriteLine($" - size : {documentInfo.Size}");
    Console.WriteLine($" - page count : {documentInfo.PageCount}");
    Console.WriteLine($"Metadata signatures : {documentInfo.MetadataSignatures.Count}");
    foreach (MetadataSignature metadataSignature in documentInfo.MetadataSignatures)
    {
        Console.WriteLine($" - {metadataSignature.Name} = {metadataSignature.Value} ({metadataSignature.Type})");
    }
}

To add metadata entries, fill a MetadataSignOptions instance with metadata signatures of the class matching your document format and pass it to the Sign method. The value type you assign — string, integer, date or floating-point number — is preserved and detected back on search:

string filePath = "sample.pdf";
string outputFilePath = "SignedWithMetadata.pdf";

using (Signature signature = new Signature(filePath))
{
    MetadataSignOptions options = new MetadataSignOptions();
    options
        .Add(new PdfMetadataSignature("Author", "Mr.Sherlock Holmes")) // String value
        .Add(new PdfMetadataSignature("CreatedOn", DateTime.Now))      // DateTime value
        .Add(new PdfMetadataSignature("DocumentId", 123456));          // Integer value

    SignResult result = signature.Sign(outputFilePath, options);
    Console.WriteLine($"Document signed with {result.Succeeded.Count} metadata signature(s).");
}

For other document families replace PdfMetadataSignature with WordProcessingMetadataSignature, SpreadsheetMetadataSignature, PresentationMetadataSignature or ImageMetadataSignature — the pattern stays the same.

The Search method with SignatureType.Metadata reads the metadata entries back. Each result reports its detected Type, and the conversion methods (ToInteger, ToDateTime, ToDouble, ToBoolean, ToString and others) return the value as a proper .NET type. The following example searches the document produced by the previous snippet:

string filePath = "SignedWithMetadata.pdf";

using (Signature signature = new Signature(filePath))
{
    List<PdfMetadataSignature> signatures = signature.Search<PdfMetadataSignature>(SignatureType.Metadata);
    Console.WriteLine($"Found {signatures.Count} metadata signature(s).");
    foreach (PdfMetadataSignature mdSignature in signatures)
    {
        switch (mdSignature.Type)
        {
            case MetadataType.Integer:
                Console.WriteLine($" - {mdSignature.Name} as integer = {mdSignature.ToInteger()}");
                break;
            case MetadataType.DateTime:
                Console.WriteLine($" - {mdSignature.Name} as date = {mdSignature.ToDateTime().ToShortDateString()}");
                break;
            case MetadataType.Double:
                Console.WriteLine($" - {mdSignature.Name} as double = {mdSignature.ToDouble()}");
                break;
            default:
                Console.WriteLine($" - {mdSignature.Name} as string = {mdSignature.ToString()}");
                break;
        }
    }
}

To narrow the results, pass a MetadataSearchOptions instance with the Name and NameMatchType filters. When a metadata entry holds a whole serialized object, retrieve it with the generic GetData<T>() method — see the secure metadata topics below.

• Get document information — file type, size, pages and their dimensions.
• Obtain document form fields and signatures information — the extended document view including the MetadataSignatures collection.

• eSign document with Metadata signature — the per-format signing guides for PDF, Word processing, Spreadsheet, Presentation and image documents.
• Sign document with Metadata signature - advanced — overview of the advanced metadata signing features.

• How to search for Metadata signatures — the basic metadata search.
• Advanced search for Metadata signatures — reading values with the typed conversion methods.
• Search for built-in Metadata signatures — reading standard document properties with IncludeBuiltinProperties.

• Sign document with secure custom Metadata signatures — encryption and custom serialization of metadata values.
• Sign documents with encrypted metadata text — protecting string values with symmetric encryption.
• Sign documents with Metadata embedded object — storing whole custom objects inside a metadata entry.
• Search for embedded and encrypted objects in Metadata signatures — retrieving protected values with GetData<T>().
• Search for encrypted text in Metadata signatures — decrypting string values on search.
• Search for encrypted objects Metadata signatures — decrypting embedded objects on search.

To learn more about document eSign features, please refer to the advanced usage section.

You may easily run the code above and see the feature in action in our GitHub examples:

• GroupDocs.Signature for .NET examples, plugins, and showcase
• GroupDocs.Signature for Java examples, plugins, and showcase
• Document Signature for .NET MVC UI Example
• Document Signature for .NET App WebForms UI Example
• Document Signature for Java App Dropwizard UI Example
• Document Signature for Java Spring UI Example

Along with the full-featured .NET library, we provide simple but powerful free online apps.

To sign PDF, Word, Excel, PowerPoint, and other documents you can use the online apps from the GroupDocs.Signature App Product Family.