JsonWorkspace

Definition

Namespace: Corvus.Text.Json
Assembly: Corvus.Text.Json.dll
Source: JsonWorkspace.cs

A workspace for manipulating JSON documents.

public class JsonWorkspace : IDisposable

Inheritance

Object → JsonWorkspace

Implements

IDisposable

Properties

Property	Type	Description
Options	`JsonWriterOptions`	Gets the JsonWriterOptions

Methods

Method	Description
Create(int, Nullable<JsonWriterOptions>) `static`	Creates an instance of a `JsonWorkspace`.
CreateBuilder	Creates a document builder for building mutable JSON documents from an existing element.
CreateUnrented(int, Nullable<JsonWriterOptions>) `static`	Creates an instance of a `JsonWorkspace`.
Dispose()	Disposes the workspace. If the workspace was rented from the cache, returns it; otherwise disposes all child documents and returns the backing array to the pool.
RegisterDocument(IWorkspaceManagedDocument)	Registers a workspace-managed document so that it will be disposed when the workspace is disposed or reset. Use this for pooled documents (e.g., `FixedJsonValueDocument`) that are created outside o...
RentWriter(IBufferWriter<byte>)	Rents a UTF-8 JSON writer from the pool that writes to the specified buffer writer.
RentWriterAndBuffer	Rents a UTF-8 JSON writer and associated buffer writer from the pool.
Reset()	Resets the workspace for reuse, disposing all workspace-managed documents and clearing the document tracking state. The backing array is retained so subsequent evaluations avoid re-allocation.
ReturnWriter(Utf8JsonWriter)	Returns a rented UTF-8 JSON writer to the pool.
ReturnWriterAndBuffer(Utf8JsonWriter, IByteBufferWriter)	Returns a rented UTF-8 JSON writer and buffer writer to the pool.

Examples

A JsonWorkspace manages pooled memory for mutable JSON operations. Always use a using statement to ensure resources are returned.

using JsonWorkspace workspace = JsonWorkspace.Create();

// Parse directly into a mutable builder (recommended when mutating)
using var builder = JsonDocumentBuilder<Person.Mutable>.Parse(
    workspace, personJson);

Person.Mutable root = builder.RootElement;
root.SetAge(31);

You can also create a builder from an existing ParsedJsonDocument if you want to retain an immutable copy of the original (e.g., for comparison or auditing):

using ParsedJsonDocument<Person> doc =
    ParsedJsonDocument<Person>.Parse(personJson);
using var builder = doc.RootElement.CreateBuilder(workspace);

Several JsonDocumentBuilder<T> instances can share a single workspace:

using JsonWorkspace workspace = JsonWorkspace.Create();

using var builder1 = doc1.RootElement.CreateBuilder(workspace);
using var builder2 = doc2.RootElement.CreateBuilder(workspace);

Zero-allocation writing with pooled writers

Rent a Utf8JsonWriter and buffer from the workspace for high-throughput serialization. The workspace manages a thread-local cache of writers and buffers, so repeated rent/return cycles are allocation-free:

using JsonWorkspace workspace = JsonWorkspace.Create();

Utf8JsonWriter writer = workspace.RentWriterAndBuffer(
    defaultBufferSize: 1024,
    out IByteBufferWriter bufferWriter);
try
{
    person.WriteTo(writer);
    writer.Flush();

    ReadOnlySpan<byte> utf8Json = bufferWriter.WrittenSpan;
}
finally
{
    workspace.ReturnWriterAndBuffer(writer, bufferWriter);
}

Applies To

Product	Versions
.NET	9, 10
.NET Standard	2.0, 2.1

Collaborate with us on GitHub

The source for this content can be found on GitHub, where you can also create and review issues and pull requests.

Open an issue