---
title: "Set DOCX custom properties in C#"
url: https://recursiveai.org/onedocument/cookbook/set-office-custom-document-properties/
description: "Set typed custom properties and core metadata in a DOCX file with C#. Save and reopen text, numbers, booleans and dates with OneDocument."
version: "1.0.0"
---

Custom properties store named metadata outside the document’s body.

```shell
dotnet add package RecursiveAI.OneDocument.Documents
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/onedocument/cookbook/set-office-custom-document-properties/set-office-custom-document-properties.zip), 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.

```csharp
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:

```text
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](https://recursiveai.org/onedocument/docs/docx-stories-properties/).

## Variations

**Add decimal and large integer values, then remove a property.** Run after the full program:

```csharp
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);
```

```text
0.25
5000000000
True
```

## Related recipes

- [Create a Word document](https://recursiveai.org/onedocument/cookbook/create-word-document/)
- [Add Word comments](https://recursiveai.org/onedocument/cookbook/add-word-comments/)

## 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](https://recursiveai.org/onedocument/docs/docx-stories-properties/) 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.
