Custom properties store named metadata outside the document’s body.
dotnet add package RecursiveAI.OneDocument.DocumentsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneDocument.Documents; using var doc = Document.Create(); doc.Properties.Custom.SetString( "Project", "Atlas"); doc.SaveAs("properties.docx");
Writes properties.docx with a text property named Project. The snippet prints nothing.
Unzip the example, then dotnet run.
Full program
The program creates its own input: a document whose body says “Delivery plan”. It sets the title and creator, plus text, integer, boolean and date custom properties. It then closes and reopens the saved file. The lowercase project lookup demonstrates that custom property names ignore case.
using RecursiveAI.OneDocument.Documents; using (var doc = Document.Create()) { doc.Body.AddParagraph("Delivery plan"); doc.Properties.Core.Title = "Delivery plan"; doc.Properties.Core.Creator = "Morgan"; var custom = doc.Properties.Custom; custom.SetString("Project", "Atlas"); custom.SetInt32("Revision", 3); custom.SetBoolean("Approved", true); custom.SetDateTime("Due", new DateTimeOffset(2026, 12, 1, 0, 0, 0, TimeSpan.Zero)); doc.SaveAs("properties.docx"); } using var reopened = Document.Open("properties.docx"); var values = reopened.Properties.Custom; Console.WriteLine($"Title: {reopened.Properties.Core.Title}"); Console.WriteLine($"Creator: {reopened.Properties.Core.Creator}"); Console.WriteLine($"Project: {values.Find("project")?.AsString}"); Console.WriteLine($"Revision: {values.Find("Revision")?.AsInt32}"); Console.WriteLine($"Approved: {values.Find("Approved")?.AsBoolean}"); Console.WriteLine($"Due: {values.Find("Due")?.AsDateTime:yyyy-MM-dd HH:mm:ss zzz}");
dotnet run prints:
Title: Delivery plan Creator: Morgan Project: Atlas Revision: 3 Approved: True Due: 2026-12-01 00:00:00 +00:00
An unreadable properties part is reported rather than overwritten; see the properties documentation.
Variations
Add decimal and large integer values, then remove a property. Run after the full program:
using RecursiveAI.OneDocument.Documents; using var doc = Document.Open("properties.docx"); var custom = doc.Properties.Custom; custom.SetDouble("Ratio", 0.25); custom.SetInt64("Total", 5_000_000_000); custom.Remove("Project"); doc.SaveAs("revised.docx"); using var back = Document.Open("revised.docx"); Console.WriteLine(back.Properties.Custom.Find("Ratio")?.AsDouble); Console.WriteLine(back.Properties.Custom.Find("Total")?.AsInt64); Console.WriteLine(back.Properties.Custom.Find("Project") is null);
0.25 5000000000 True
Related recipes
The short answer
To set DOCX custom properties in C#, create or open a Document, call the typed setters on doc.Properties.Custom, and save with SaveAs. Use doc.Properties.Core for standard fields such as title and creator. Reopen the saved document and read the matching typed accessor to check the value, rather than relying on the document’s visible text.
The OneDocument properties documentation describes core, extended and custom properties on the Office package. The example uses the released Documents package and creates the input itself, so no Word installation or template file is part of this workflow.
What is document properties in Word?
Document properties are metadata. The title in the core properties is a separate value from the first paragraph, even when both contain the same words. Setting one does not mean you have edited the other. The program above deliberately writes “Delivery plan” to both locations so you can choose which value your application owns.
OneDocument exposes three groups. Core properties live in docProps/core.xml, extended properties in docProps/app.xml, and custom properties in docProps/custom.xml. Use the core title and creator when those fields fit. Use a custom name such as Project or Approved for an application-specific value. Extended properties hold fields such as company and application; they are not another collection of arbitrary custom names.
The properties API creates a missing part with its relationship and content type on the first write. An unedited part stays byte-identical, and an edit keeps the other elements in order. You do not need to manufacture the XML part before calling a setter.
How to change docx metadata?
For an existing DOCX, replace Document.Create() with Document.Open("input.docx") and save under an output filename. Keep the same typed setters. The variation above demonstrates opening the generated document, changing the custom collection and writing a new file.
Choose a setter that matches the data, not its screen representation. SetString writes text; SetInt32 and SetInt64 write integers; SetDouble writes a floating-point value; SetBoolean writes a boolean; and SetDateTime writes a date. A revision number stored as text is not the same custom-property type as an integer. On readback, use AsInt32, AsInt64, AsDouble, AsBoolean or AsDateTime as appropriate.
Names compare ignoring case. Project and project therefore refer to the same custom property, not two independent fields. When adding a property, the API assigns the next property ID after the highest existing ID; it does not renumber the others. Unknown value types are read as text and kept, rather than being automatically converted to one of the supported types.
Dates are explicit. The library does not read the clock to update document properties, and no date changes by itself. The documented date representation is UTC to the second. Supply the intended instant and check the reopened value, as the full program does with its due date.
Finally, metadata authoring is not visible-text replacement or a cleanup operation. This recipe sets selected fields. It does not promise to remove unrelated metadata, change comments or update a field displayed in the document body. Keep those tasks separate from the code that assigns your project’s metadata.