# Write YAML Files from .NET

Write YAML from .NET objects, build a new YAML document by path, stream large output with YamlWriter, and convert JSON or TOML to YAML.

**Packages**

- [OfficeIMO.Yaml](https://www.nuget.org/packages/OfficeIMO.Yaml) `dotnet add package OfficeIMO.Yaml`
- [OfficeIMO.Data.Conversions](https://www.nuget.org/packages/OfficeIMO.Data.Conversions) `dotnet add package OfficeIMO.Data.Conversions`

**Works with**

- .NET
- [PowerShell](/docs/pswriteoffice/install/) `Install-Module PSWriteOffice`
- [CLI](/docs/cli/install/) `dotnet tool install --global OfficeIMO.Tool`

**Target frameworks**

netstandard2.0, net8.0, net10.0, net472

**APIs**

- [`OfficeConversionReport`](/api/core/officeimo-officeconversionreport/)
- [`OfficeDiagnostic`](/api/core/officeimo-officediagnostic/)

**Cmdlets**

- [`ConvertTo-OfficeYaml`](/api/powershell/convertto-officeyaml/)
- [`Export-OfficeYaml`](/api/powershell/export-officeyaml/)
- [`New-OfficeYaml`](/api/powershell/new-officeyaml/)
- [`Set-OfficeYamlNode`](/api/powershell/set-officeyamlnode/)

**Commands**

- [`officeimo convert`](/docs/cli/convert/)

**Limits**

[OfficeIMO.Data.Conversions support matrix](/compatibility/#package-data-conversions)

**Verified**

Examples compiled against the source on 2026-11-14

**Data**

- [OfficeIMO.Yaml API index](/api/yaml/index.json)
- [PSWriteOffice command catalog](/data/powershell/commands.json)
- [CLI command catalog](/data/cli/commands.json)
- [Capability catalog (JSON)](/data/capabilities.json)

Pick the writer by where the data comes from. `YamlSerializer` writes objects you already have. A new `YamlDocument` builds a file by path, which suits small configuration files you assemble from settings. `YamlWriter` is a forward-only emitter for large or generated output that should not be held in memory. All three write deterministic output and quote strings that YAML 1.1 readers would otherwise read as booleans or numbers.

## Write objects as YAML

### C#

```csharp
using OfficeIMO;
using OfficeIMO.Yaml;

var config = new ServiceConfig {
    Name = "web",
    Replicas = 3,
    Ports = { 80, 443 },
    Labels = { ["app"] = "web", ["tier"] = "yes" }
};

var options = new YamlSerializerOptions {
    PropertyNamingPolicy = OfficeNamingPolicy.CamelCase,
    DefaultIgnoreCondition = OfficeIgnoreCondition.WhenWritingNull
};
File.WriteAllText("service.yaml", YamlSerializer.Serialize(config, options));

public sealed class ServiceConfig {
    public string Name { get; set; } = "";
    public int Replicas { get; set; }
    public List<int> Ports { get; set; } = new();
    public Dictionary<string, string> Labels { get; set; } = new();
    public string? Description { get; set; }
}
```

The output is:

```yaml
name: web
replicas: 3
ports:
- 80
- 443
labels:
  app: web
  tier: 'yes'
```

`[OfficePropertyName]` sets a key and wins over the naming policy, and `[OfficeIgnore]` leaves a property out. With `ReferenceHandling = YamlReferenceHandling.Preserve`, an object reached twice is written as an anchor and an alias instead of failing as a cycle.

### PowerShell

```powershell
[ordered]@{ name = 'web'; replicas = 3; ports = 80, 443 } | ConvertTo-OfficeYaml

[ordered]@{ logging = [ordered]@{ level = 'Information' }; retries = 3 } |
    Export-OfficeYaml -Path ./settings.yaml
```

## Build a new YAML file by path

`YamlDocument.Create(path)` starts an empty document for a file without writing it. `Set` creates the mappings on the way, and comments can be set as you go.

### C#

```csharp
using OfficeIMO.Yaml;

using YamlDocument document = YamlDocument.Create("values.yaml");
document.Set("image.repository", "nginx");
document.Set("image.tag", "1.27.2");
document.Set("replicaCount", 2);
document.Add("ingress.hosts", "example.com");
document.Select("image.tag")!.SetComment("updated by the release pipeline");
document.Save();
```

### PowerShell

```powershell
New-OfficeYaml -Path ./values.yaml {
    Set-OfficeYamlNode -Select 'image.repository' -Value 'nginx'
    Set-OfficeYamlNode -Select 'image.tag' -Value '1.27.2'
    Set-OfficeYamlNode -Select 'replicaCount' -Value 2
}
```

## Stream YAML with YamlWriter

`YamlWriter` writes events in order to a stream or `TextWriter`. It allocates nothing per call beyond its pooled buffer, never folds long lines, and writes multi-line strings as literal block scalars.

### C#

```csharp
using OfficeIMO.Yaml;

using FileStream stream = File.Create("inventory.yaml");
using var writer = new YamlWriter(stream);   // UTF-8 without a byte-order mark

writer.WriteStartSequence();
foreach (string host in new[] { "web-01", "web-02", "db-01" }) {
    writer.WriteStartMapping();
    writer.WriteKey("host");
    writer.WriteScalar(host);
    writer.WriteKey("enabled");
    writer.WriteScalar("yes");                // written 'yes', so YAML 1.1 readers keep it a string
    writer.WriteKey("ports");
    writer.WriteStartSequence(YamlStyle.Flow);
    writer.WriteScalar(80);
    writer.WriteScalar(443);
    writer.WriteEndSequence();
    writer.WriteEndMapping();
}
writer.WriteEndSequence();
```

`YamlWriterOptions` sets the mapping indent, sequence indent, dash offset and line break: 2, 2 and 0 write `key:\n- item`, while 2, 4 and 2 write `key:\n - item`.

## Convert JSON or TOML to YAML

Structured-data conversion streams events from one format's reader to another's writer, so numbers keep their exact text and comments travel between YAML and TOML.

### C#

```csharp
using System.Text.Json.Nodes;
using OfficeIMO;
using OfficeIMO.Data.Conversions;
using OfficeIMO.Toml;

JsonNode.Parse(File.ReadAllText("appsettings.json")).SaveAsYaml("appsettings.yaml");

using TomlDocument cargo = TomlDocument.Load("Cargo.toml");
OfficeConversionReport report = cargo.SaveAsYaml("cargo.yaml");   // comments travel with their keys
foreach (OfficeDiagnostic diagnostic in report.Diagnostics) Console.WriteLine(diagnostic.Message);
```

### CLI

```sh
officeimo convert appsettings.json appsettings.yaml
officeimo convert Cargo.toml cargo.yaml --require-no-loss
```

See [data conversions](/docs/data-conversions/) for every source and target format and the loss report.

<!-- PowerForge markdown artifact sha256:E70DDE3512F21C6D9E2EB5F3A5995FF32C4B23D98534824873B196E6C2B64501 -->
