Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ProwlEngine/Prowl.Echo/llms.txt

Use this file to discover all available pages before exploring further.

Every format in Prowl.Echo operates on the same EchoObject tree. You serialize your .NET object once into an EchoObject, then write it to whichever format — or formats — you need. There is no separate serialization path per format; the intermediate representation is shared, and switching formats is a one-line change.

​
How it works

Prowl.Echo’s format system is built on the IFileFormat interface. Each format class implements WriteTo(EchoObject, Stream) and ReadFrom(Stream), and a set of extension methods on that interface provides string, byte array, and file-path convenience overloads for every format automatically. 
// Serialize once
EchoObject echo = Serializer.Serialize(myObject);

// Write to any format
string   jsonText  = echo.WriteToJson();
string   yamlText  = echo.WriteToYaml();
string   xmlText   = echo.WriteToXml();
string   echoText  = echo.WriteToString();
byte[]   bsonBytes = echo.WriteToBson();
echo.WriteToBinary(new FileInfo("data.bin"));

// Read back from any format
EchoObject fromJson  = EchoObject.ReadFromJson(jsonText);
EchoObject fromYaml  = EchoObject.ReadFromYaml(yamlText);
EchoObject fromXml   = EchoObject.ReadFromXml(xmlText);
EchoObject fromEcho  = EchoObject.ReadFromString(echoText);
EchoObject fromBson  = EchoObject.ReadFromBson(bsonBytes);
EchoObject fromBin   = EchoObject.ReadFromBinary(new FileInfo("data.bin"));

​
Format comparison

Echo Binary

The fastest and most compact option. Supports two encoding modes: Performance (fixed-width integers, fastest) and Size (LEB128 + LZW string compression, smallest). Not human-readable. Preserves every EchoType exactly. Best for runtime storage, save files, and network payloads.

Echo Text

Prowl.Echo’s native text format. Human-readable, lossless, and ideal for version-controlled configuration or debugging. Uses typed suffixes (42L, 3.14F, 255B) so every numeric type round-trips perfectly.

JSON

Standard JSON output with no external dependencies. Accepts any generic JSON as input, making it suitable for REST API integration. Some type precision is lost on round-trip (e.g., byte/short → int, float → double).

BSON

Binary JSON following the BSON spec. Produces a byte[] directly. Good for MongoDB interop and binary JSON pipelines. Like JSON, some type distinctions are coalesced (e.g., float → double, decimal → string).

YAML

Clean, human-readable YAML with no external dependencies. Accepts both Echo-produced and generic YAML as input. Well suited for config files and tools that already speak YAML. Some type precision is lost on round-trip.

XML

Standard XML 1.0 with type attributes that preserve all EchoType values during round-trips. Also reads generic XML without type attributes, inferring types from content. Good for interop with legacy systems and SOAP/XML pipelines.

​
The IFileFormat interface

All six formats implement IFileFormat: 
public interface IFileFormat
{
    void WriteTo(EchoObject tag, Stream stream);
    EchoObject ReadFrom(Stream stream);
}
The FileFormatExtensions class adds the following convenience methods to every IFileFormat, so you can use them with any built-in or custom format:
MethodDescription
WriteToString(EchoObject)Serialize to a UTF-8 string (best for text formats)
ReadFromString(string)Deserialize from a UTF-8 string
WriteToBytes(EchoObject)Serialize to a byte[]
ReadFromBytes(byte[])Deserialize from a byte[]
WriteToFile(EchoObject, string)Write directly to a file path
ReadFromFile(string)Read directly from a file path
These methods wrap any IFileFormat implementation, including your own custom formats.

​
Quick-access singletons

Every built-in format exposes a thread-safe singleton instance. You can use the singleton directly when you need access to format-level settings (such as BinarySerializationOptions or JsonFileFormat.Indented): 
// Use the singleton to access format options
JsonFileFormat.Instance.Indented = false;
string compact = JsonFileFormat.Instance.WriteToString(echo);

// Apply binary options via the singleton
EchoBinaryFormat.Instance.Options = new BinarySerializationOptions
{
    EncodingMode = BinaryEncodingMode.Size
};
byte[] packed = EchoBinaryFormat.Instance.WriteToBytes(echo);

​
Choosing the right format

Production storage & networking

Use Echo binary with BinaryEncodingMode.Size for the smallest payloads, or BinaryEncodingMode.Performance when read/write speed matters most.

Debugging & version control

Use Echo text. It is human-readable, produces clean diffs, and is the only text format that preserves every EchoType exactly.

External interop

Use JSON for REST APIs and web tooling, YAML for configuration files, XML for legacy systems, and BSON for MongoDB or binary JSON pipelines.
JSON, BSON, YAML, and the XML generic-read path do not preserve all EchoType distinctions. For example, JSON collapses byte, short, and int to a plain JSON number, which is read back as int. If you need a lossless round-trip, use Echo binary or Echo text.

Build docs developers (and LLMs) love

Get started for freeTalk to us