TLio.FormatConverter
1.6.0-preview.1
dotnet add package TLio.FormatConverter --version 1.6.0-preview.1
NuGet\Install-Package TLio.FormatConverter -Version 1.6.0-preview.1
<PackageReference Include="TLio.FormatConverter" Version="1.6.0-preview.1" />
<PackageVersion Include="TLio.FormatConverter" Version="1.6.0-preview.1" />
<PackageReference Include="TLio.FormatConverter" />
paket add TLio.FormatConverter --version 1.6.0-preview.1
#r "nuget: TLio.FormatConverter, 1.6.0-preview.1"
#:package TLio.FormatConverter@1.6.0-preview.1
#addin nuget:?package=TLio.FormatConverter&version=1.6.0-preview.1&prerelease
#tool nuget:?package=TLio.FormatConverter&version=1.6.0-preview.1&prerelease
TLio.FormatConverter
The convert and convertValue commands for TLio, plus
MultiFormatScriptRunner — the piece that lets one script change the document's format partway
through — and the JSON, XML and YAML converters they work through. One assembly, one package.
dotnet add package TLio.FormatConverter
Two commands, and what changes format
convertchanges the whole document. That means a differentTNode, which noICommand<TNode>can return — so the engine cannot run it.MultiFormatScriptRunnersplits the script at each boundary and re-hosts each section on the engine for that format. Run on a bare engine it converts nothing and says so.convertValuechanges one value at a path. The document's format never changes, so it is an ordinary command on the ordinary engine — the embedded-payload case, an XML string inside a JSON envelope.
Paths after a convert speak the new format's path language. That is inherent: the paths
address the document, and the document has changed format.
Quick start
using TLio.FormatConverter; // the commands and the runner
using TLio.FormatConverter.Core; // the converter itself
using TLio.FormatConverter.Json; // the three adapters
using TLio.FormatConverter.Xml;
using TLio.FormatConverter.Yaml;
// Fully qualified: the type's name repeats a namespace segment, so a bare
// `new FormatConverter()` is only unambiguous where `using TLio;` is absent.
var converter = new TLio.FormatConverter.Core.FormatConverter();
converter.Register(new JsonFormatAdapter());
converter.Register(new XmlFormatAdapter());
converter.Register(new YamlFormatAdapter());
var runner = new MultiFormatScriptRunner(converter);
runner.RegisterExecutor(new ScriptEngineSectionExecutor<JToken>(
"json", jsonEngine, JsonExecutionContext.CreateDefault));
runner.RegisterExecutor(new ScriptEngineSectionExecutor<XElement>(
"xml", xmlEngine, XmlExecutionContext.CreateWithNativeXPath));
runner.RegisterExecutor(new ScriptEngineSectionExecutor<YamlNode>(
"yaml", yamlEngine, YamlExecutionContext.CreateDefault));
var result = runner.Run("json", document, script);
// result.Document, result.FormatId, result.Success, result.Logs
The script:
[
{ "command": "add", "path": "$.order.status", "value": "new" },
{ "command": "convert", "to": "yaml" },
{ "command": "add", "path": "order.source", "value": "portal" },
{ "command": "convert", "to": "xml" },
{ "command": "rename", "path": "/order", "name": "opdracht" }
]
MultiFormatScriptRunner.CrossesAFormatBoundary(script) is how a host decides whether a script
needs the runner or a plain ScriptEngine.
Registering the commands on an engine
convertValue works on any engine; convert still needs the runner, but registering it means a
script that uses it inline gets an explanation rather than "unknown command".
var options = ParseOptions<JToken>.CreateDefault()
.WithFormatConversion(converter, "json");
Both arguments are required: the format id ("json" for a JToken engine, "xml" for
XElement, "yaml" for YamlNode) decides whether convertValue writes its result back as
structure or as a string. Leaving this call out does not fail — convertValue parses as an
unknown command, logs a warning, and the script succeeds with the document unchanged.
options.CommandsProvider.RegisterFormatConversion<JToken>(converter, "json") is the older
spelling and still works.
Settings
Per-boundary, and they do not carry to the next convert: attributePrefix, textProperty,
namespacePrefix, arrayItemName, arrayHandling, nullRepresentation, nameSanitization,
inferTypes, cdataAsText, flattenAnchors. Each exists where the formats genuinely disagree.
convertValue adds two: valueOnly (convert the value without the node's own name, so a value
written to XML or YAML and read back is exactly what it was) and rootName (the root element
XML needs, root by default, dropped again on the way back). valueOnly is on by default; valueOnly: false restores the 1.5.0 output.
Conversion output is the canonical document shape TLio's own adapters address, so the commands after a boundary land where the paths say they do.
License
MIT — see the repository.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- TLio.Client (>= 1.6.0-preview.1)
- TLio.Core (>= 1.6.0-preview.1)
- YamlDotNet (>= 18.1.0)
-
net8.0
- TLio.Client (>= 1.6.0-preview.1)
- TLio.Core (>= 1.6.0-preview.1)
- YamlDotNet (>= 18.1.0)
-
net9.0
- TLio.Client (>= 1.6.0-preview.1)
- TLio.Core (>= 1.6.0-preview.1)
- YamlDotNet (>= 18.1.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.6.0-preview.1 | 79 | 11/3/2026 |
| 1.5.2 | 82 | 11/16/2026 |
| 1.5.1 | 144 | 11/2/2026 |
| 1.5.0 | 115 | 11/2/2026 |
| 1.5.0-preview.5 | 60 | 11/2/2026 |
| 1.5.0-preview.3 | 74 | 10/23/2026 |
| 1.5.0-preview.2 | 65 | 10/23/2026 |
| 1.5.0-preview.1 | 65 | 10/22/2026 |
| 1.4.1 | 114 | 10/22/2026 |
| 1.4.0 | 130 | 10/19/2026 |
| 1.3.0 | 112 | 10/19/2026 |
| 1.3.0-preview.9 | 63 | 10/19/2026 |
| 1.3.0-preview.8 | 58 | 10/19/2026 |
| 1.3.0-preview.7 | 57 | 10/19/2026 |
| 1.3.0-preview.6 | 57 | 10/19/2026 |
| 1.3.0-preview.5 | 61 | 10/19/2026 |
| 1.3.0-preview.4 | 59 | 10/19/2026 |
| 1.3.0-preview.3 | 68 | 10/18/2026 |
| 1.3.0-preview.2 | 68 | 10/18/2026 |
| 1.3.0-preview.1 | 73 | 10/12/2026 |