Add Import-Yaml and Export-Yaml file I/O functions

[MariusStorhaug]

Why

Scripts and automation that work with YAML configuration files currently require a two-step pattern to read or write YAML (Get-Content -Raw | ConvertFrom-Yaml / ConvertTo-Yaml | Set-Content). Every other PowerShell serialization format ships a Convert* pair and an Import-/Export- pair for direct file I/O — Import-Csv / Export-Csv, Import-Clixml / Export-Clixml — so users expect the same convenience for YAML.

What

An Import-Yaml function that reads a YAML file and returns a PowerShell object, and an Export-Yaml function that serializes a PowerShell object directly to a YAML file. Both delegate serialization logic to the existing ConvertFrom-Yaml and ConvertTo-Yaml functions, adding only the file I/O layer and the standard parameters that PowerShell file cmdlets provide.

$config = Import-Yaml -Path config.yaml
$config | Export-Yaml -Path config.yaml

Standard PowerShell Import/Export parameters

Parameter	Import-Yaml	Export-Yaml	Description
-Path	✓	✓	File path (position 0, wildcards allowed on import)
-LiteralPath	✓	✓	Literal file path (no wildcard expansion)
-Encoding	✓	✓	File encoding (default: utf8NoBOM, consistent with PowerShell 7+)
-InputObject	—	✓	Object to export (ValueFromPipeline)
-NoClobber	—	✓	Fail if the output file already exists
-Force	—	✓	Overwrite read-only files
-Append	—	✓	Append to existing file instead of overwriting

YAML-specific parameters (passthrough from Convert functions)

Parameter	Import-Yaml	Export-Yaml	Source
-AsHashtable	✓	—	ConvertFrom-Yaml
-NoEnumerate	✓	—	ConvertFrom-Yaml
-Depth	✓	✓	Both
-EnumsAsStrings	—	✓	ConvertTo-Yaml
-AsArray	—	✓	ConvertTo-Yaml
-Indent	—	✓	ConvertTo-Yaml

Pipeline behavior

• Import-Yaml — -Path accepts [string[]] and pipeline input by property name. Returns [PSCustomObject] or [OrderedDictionary] per file.
• Export-Yaml — -InputObject accepts pipeline input. Writes to the file and returns nothing (void), consistent with Export-Csv. Buffers all pipeline input before writing (same as ConvertTo-Yaml).

Aliases

Import-Yml for Import-Yaml, Export-Yml for Export-Yaml — matching the existing ConvertFrom-Yml / ConvertTo-Yml alias pattern.

Acceptance criteria

• Import-Yaml -Path file.yaml returns the same object as Get-Content file.yaml -Raw | ConvertFrom-Yaml
• $obj | Export-Yaml -Path file.yaml produces the same file content as $obj | ConvertTo-Yaml | Set-Content file.yaml
• -NoClobber prevents overwriting an existing file
• -Force overwrites read-only files
• -Append appends serialized YAML to an existing file (with a document separator --- between entries)
• -Encoding controls file encoding (default utf8NoBOM)
• -LiteralPath works with paths containing wildcard characters
• All YAML-specific parameters pass through to the underlying Convert functions
• Pipeline input works for both functions
• ShouldProcess support (-WhatIf, -Confirm) on Export-Yaml

Related

• Add ConvertFrom-Yaml and ConvertTo-Yaml functions #2 — ConvertFrom-Yaml / ConvertTo-Yaml (prerequisite — already implemented)
• Support multi-document YAML streams #21 — Multi-document streams (affects -Append round-trip behavior)

[MariusStorhaug]

What changed: Reformatted the issue body to the MSXOrg Issue Format — a local Why plus an outcome-level What/acceptance criteria. Removed the Technical Decisions and Implementation Plan sections (and other implementation-tradeoff notes).
Why: Issue bodies should state local purpose and observable outcome without leaking implementation detail into the outcome-level description; durable technical decisions belong in the PR/design, not the tracking issue.
Follow-up: None.