Arbeiten mit Dokumenteigenschaften

Dieser Leitfaden zeigt, wie man die Metadaten eines Word-Dokuments liest und verwaltet – die im Info/ Eigenschaften-Panel von Word sichtbaren Eigenschaften sowie alle anwendungsspezifischen benutzerdefinierten Werte. Document.BuiltInDocumentProperties und Document.CustomDocumentProperties stellen diese beiden Kategorien bereit, die letztlich beide auf derselben zugrunde liegenden DocumentProperty-Darstellung basieren.

Integrierte Dokumenteigenschaften

Document.BuiltInDocumentProperties gibt eine BuiltInDocumentProperties-Sammlung zurück, die die standardmäßigen Metadaten enthält, die Word für jedes Dokument verfolgt: beschreibende Felder wie Title, Subject, Author, Manager, Company, Category, Keywords und Comments; Zeitstempel wie CreatedTime, LastSavedTime und LastPrinted, zusammen mit LastSavedBy und RevisionNumber; sowie Statistiken wie Words, Characters, CharactersWithSpaces, Lines, Paragraphs und Pages. Security meldet den Schutzstatus des Dokuments als DocumentSecurity-Wert, und Template, NameOfApplication und TotalEditingTime beschreiben die Autorenumgebung. Da BuiltInDocumentProperties ein fester, bekannter Satz von Eigenschaften ist, werden einzelne Werte als gewöhnliche Eigenschaften (BuiltInDocumentProperties.Author = "...") gelesen und geschrieben, anstatt sie über den Namen nachzuschlagen.

Benutzerdefinierte Dokumenteigenschaften

Document.CustomDocumentProperties gibt eine CustomDocumentProperties-Sammlung zurück für anwendungsspezifische Metadaten, die nicht Teil des integrierten Word-Satzes sind. Mehrere Add(name, value)-Überladungen erzeugen eine neue Eigenschaft aus einem Namen und einem typisierten Wert (String, Zahl, Boolesch oder Datum, je nach Überladung), und AddLinkToContent(name, linkSource) erstellt eine Eigenschaft, deren Wert mit einem Lesezeichen-Bereich im Dokument verknüpft ist und diesen verfolgt, anstatt einen statischen Wert zu halten. Das Indizieren nach Name (z.B. properties[name]) und Contains(name) suchen eine Eigenschaft, IndexOf(name) gibt ihre Position zurück, und Remove(name)/RemoveAt(index) löschen eine.

Das DocumentProperty-Objekt und die gemeinsam genutzte Sammlungsbasis

Sowohl BuiltInDocumentProperties als auch CustomDocumentProperties stammen vom abstrakten DocumentPropertyCollection ab, der einen Indexer nach Namen, GetEnumerator(), Contains(name), IndexOf(name) und Count definiert – sodass die beiden Sammlungen auf dieselbe Weise inspiziert werden, obwohl eingebaute Eigenschaften festgelegt und benutzerdefinierte Eigenschaften offen sind. Einzeln hat ein DocumentProperty ein Name, ein untypisiertes Value und ein Type (ein PropertyType-Enum-Wert: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray oder Other). IsLinkToContent und LinkSource melden, ob die Eigenschaft mit Dokumentinhalt verknüpft ist, anstatt einen statischen Wert zu halten (siehe AddLinkToContent oben). Da Value untypisiert ist, stellt DocumentProperty typisierte Zugriffsmethoden bereit – ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() und ToString() – um sie als einen bestimmten Typ zu lesen, ohne eine explizite Typumwandlung.

Dokumentensicherheit

BuiltInDocumentProperties.Security meldet einen DocumentSecurity-Wert, der den Schutzstatus des Dokuments beschreibt: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced oder ReadOnlyExceptAnnotations. Dies spiegelt die im Dokument gespeicherten Schutz-Metadaten wider, wie sie aus den Dateieigenschaften gelesen werden.

Tipps und bewährte Vorgehensweisen

Verwenden Sie die typisierten Zugriffsmethoden (ToInt(), ToDouble(), ToDateTime(), ToBool()) auf DocumentProperty.Value anstatt den untypisierten object-Wert direkt zu casten, da der zugrunde liegende Speichertyp je nach PropertyType variieren kann.
Prüfen Sie Contains(name), bevor Sie per Namen (z.B. properties[name]) in eine der Eigenschaftssammlungen indexieren, wenn eine Eigenschaft möglicherweise nicht existiert, um zu vermeiden, dass ein fehlender Eigenschaftsfall als Ausnahmeweg behandelt wird.
Verwenden Sie CustomDocumentProperties.AddLinkToContent(name, linkSource), wenn der Wert einer benutzerdefinierten Eigenschaft stets einen markierten Teil des Dokuments widerspiegeln soll, anstatt eine statische benutzerdefinierte Eigenschaft manuell neu zu synchronisieren, sobald sich dieser Inhalt ändert.
Betrachten Sie BuiltInDocumentProperties-Statistiken (Words, Characters, Pages und ähnliche) als die in den Dateimetadaten gespeicherten Werte und nicht als stets live berechnete Zähler – aktualisieren Sie sie explizit, wenn das Dokument seit ihrer letzten Speicherung geändert wurde.
Lese BuiltInDocumentProperties.Security, um den deklarierten Schutzstatus eines Dokuments zu prüfen, bevor entschieden wird, ob weitere schutzbezogene Verarbeitung erforderlich ist.

Häufige Probleme

Problem	Ursache	Lösung
Das Indizieren einer `CustomDocumentProperties`-Sammlung nach Namen liefert nichts Verwendbares	Die Eigenschaft existiert in diesem Dokument nicht	Rufen Sie zuerst `Contains(name)` auf, oder fügen Sie die Eigenschaft mit der entsprechenden `Add(name, value)`-Überladung hinzu
Das Auslesen des Werts einer benutzerdefinierten Eigenschaft liefert den falschen Typ	`DocumentProperty.Value` ist ein untypisiertes `object`; der Aufrufer nahm einen Typ an, der nicht zu `Type` passt	Verwenden Sie den entsprechenden typisierten Zugriff (`ToInt()`, `ToDouble()`, `ToDateTime()`, `ToBool()`, `ToByteArray()`) basierend auf `DocumentProperty.Type`
Der Wert einer verknüpften benutzerdefinierten Eigenschaft wirkt veraltet	Die Eigenschaft ist über `AddLinkToContent` verknüpft, und der verknüpfte Inhalt hat sich geändert, ohne dass das Dokument entsprechend aktualisiert wurde	Bestätigen Sie, dass der mit Lesezeichen versehene `linkSource`-Bereich weiterhin den beabsichtigten Inhalt widerspiegelt
Wortstatistiken (`Words`, `Pages` usw.) stimmen nicht mit dem tatsächlichen aktuellen Inhalt des Dokuments überein	Eingebaute Statistiken spiegeln gespeicherte Metadaten wider, nicht eine aktuelle Neuzählung	Berechnen Sie die relevanten `BuiltInDocumentProperties`-Werte neu und aktualisieren Sie sie, falls ein aktueller Zählerwert benötigt wird

FAQ

Wie lese oder setze ich den Autor und den Titel des Dokuments?

Verwende Document.BuiltInDocumentProperties.Author und .Title direkt — sie sind gewöhnliche String-Eigenschaften der BuiltInDocumentProperties-Sammlung, die von Document.BuiltInDocumentProperties aus erreicht wird.

Wie füge ich anwendungsspezifische Metadaten hinzu, die keine Standard-Word-Eigenschaft sind?

Verwende Document.CustomDocumentProperties.Add(name, value) mit dem Namen und dem Wert der Eigenschaft; die passende Add-Überladung wird basierend auf dem Typ des Werts ausgewählt.

Was ist der Unterschied zwischen `BuiltInDocumentProperties` und `CustomDocumentProperties`?

BuiltInDocumentProperties ist das feste Set von standardmäßigen Metadatenfeldern von Word (Autor, Titel, Statistiken usw.), auf das über benannte Eigenschaften zugegriffen wird. CustomDocumentProperties ist eine offene, benannte Sammlung von DocumentProperty-Werten für anwendungsdefinierte Metadaten, die über den Indexer nach Namen zugegriffen werden (z.B. properties[name]) und Contains.

Wie lese ich eine benutzerdefinierte Eigenschaft, ohne den genauen gespeicherten Typ im Voraus zu kennen?

Rufen Sie das DocumentProperty ab, indem Sie die Sammlung indizieren (z.B. properties[name]), prüfen Sie dessen Type (ein PropertyType-Wert) und verwenden Sie den passenden typisierten Zugriff wie ToInt(), ToDouble(), ToDateTime() oder ToBool() auf dessen Value.

Wie kann ich eine benutzerdefinierte Eigenschaft dazu bringen, ein Stück Dokumentinhalt nachzuverfolgen?

Verwenden Sie CustomDocumentProperties.AddLinkToContent(name, linkSource) und übergeben Sie einen Lesezeichennamen als linkSource; der Wert der Eigenschaft spiegelt dann den markierten Inhalt wider statt eines statischen Wertes.

API Reference Zusammenfassung

Klasse/Methode	Beschreibung
`Document.BuiltInDocumentProperties`	Standard-Metadatenfelder von Word (Autor, Titel, Statistiken, Sicherheit usw.)
`Document.CustomDocumentProperties`	Anwendungsspezifisch definierte benannte Metadaten-Eigenschaften
`CustomDocumentProperties.Add(name, value)`	Fügen Sie eine benutzerdefinierte Eigenschaft aus einem Namen und einem typisierten Wert hinzu
`CustomDocumentProperties.AddLinkToContent(name, linkSource)`	Fügen Sie eine benutzerdefinierte Eigenschaft hinzu, die mit dem mit Lesezeichen versehenen Dokumentinhalt verknüpft ist
`DocumentPropertyCollection`	Gemeinsame abstrakte Basisklasse für beide Eigenschaftssammlungen
`DocumentProperty`	Der Name einer einzelnen Eigenschaft, ihr untypisierter Wert und `PropertyType`
`DocumentProperty.ToInt()` / `ToDouble()` / `ToDateTime()` / `ToBool()`	Typisierte Zugriffsmethoden für den Wert einer Eigenschaft
`PropertyType`	Enum, das den Werttyp eines `DocumentProperty` beschreibt
`DocumentSecurity`	Enum, das den Schutzstatus eines Dokuments beschreibt, über `BuiltInDocumentProperties.Security`

Siehe auch

Aspose.Words for .NET — Enterprise Documentation

Arbeiten mit Dokumenteigenschaften