Recursive AI

Apply HTML edits atomically in C#

onehtml is a free, open-source HTML library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Apply a group of HTML changes as one transaction: either every edit succeeds, or none changes the document. You do not need a separate rollback call.

Terminal
dotnet add package RecursiveAI.OneHtml

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Editing;
 
var doc = Document.Parse("<p>a<br></p>");
var result = doc.Apply([
    Edit.SetAttribute(doc.Root.QuerySelector("p"), "id", "x"),
    Edit.Append(doc.Root.QuerySelector("br"), "<b>b</b>")
]);
Console.WriteLine($"Applied: {result.Succeeded}");
Console.WriteLine(doc.Source.Text);

Unzip the example, then dotnet run.

Text
Applied: False
<p>a<br></p>

The full program

This program also prints every edit’s outcome and whether a new snapshot was returned.

C#
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Editing;
 
var doc = Document.Parse("<p>a<br></p>");
var result = doc.Apply([
    Edit.SetAttribute(doc.Root.QuerySelector("p"), "id", "x"),
    Edit.Append(doc.Root.QuerySelector("br"), "<b>b</b>")
]);
Console.WriteLine($"Applied: {result.Succeeded}");
Console.WriteLine(doc.Source.Text);
foreach (var outcome in result.Outcomes)
    Console.WriteLine($"{outcome.Index}: {outcome.Status} {outcome.Reason}".TrimEnd());
Console.WriteLine($"New snapshot: {result.Document is not null}");

dotnet run prints:

Text
Applied: False
<p>a<br></p>
0: NotAttempted
1: Invalid a void element cannot have children
New snapshot: False

If any edit is invalid or cannot be expressed as HTML, Succeeded is false, Document is null, and Outcomes reports what happened without changing the original snapshot.

Variations

Apply two valid edits

These two edits commit together.

C#
using RecursiveAI.OneHtml;
using RecursiveAI.OneHtml.Editing;
 
var doc = Document.Parse("<p>a</p>");
var p = doc.Root.QuerySelector("p");
var result = doc.Apply([
    Edit.SetAttribute(p, "id", "x"),
    Edit.ReplaceText(p, "b")
]);
if (!result.Succeeded) throw new Exception(result.Failure);
Console.WriteLine(result.Document!.Source.Text);
Text
<p id="x">b</p>

The short answer

Pass all HTML edits to one Document.Apply call. Check Succeeded before using the returned Document. A failure returns no edited document, so the original snapshot remains the only document to keep. You do not need a separate rollback call.

The example deliberately tries to give a <br> element children. That cannot work: the element is void. Although setting an ID on the paragraph is valid on its own, the transaction applies neither change. The program prints the original HTML and reports why the invalid edit stopped the batch.

How do you roll back an HTML edit transaction in C#?

For onehtml’s in-memory editor, rollback means not publishing a new snapshot when any edit fails. The edit format defines a transaction as an ordered list in which “all apply or none does.” This is not a database transaction and it does not enlist file writes or other application side effects.

Keep those side effects outside the operation. In particular, do not overwrite an input file before checking Succeeded. The original Document is immutable; a successful transaction gives you another snapshot. Existing node handles still refer to the original document. Select nodes from the returned document for the next transaction, rather than reusing handles from the earlier snapshot.

The unchanged source printed by this example is not serialized from a partially modified tree. It is the original document’s source. That distinction matters if your input includes comments, unusual quotes, or whitespace that must survive a rejected change.

How do you apply multiple HTML edits in one C# example?

The successful variation above supplies two edits to the same call: set the paragraph’s ID and replace its text. Both target a paragraph from the same original snapshot. The returned source contains both changes. Calling Apply separately for each edit would instead create two independent transactions; a failure in the second would not undo the first returned snapshot.

The editing model applies operations in order. An operation later in a batch can encounter changes made earlier in that batch. For example, removing a node and then editing that removed node is invalid. Group together changes that must stand or fall together, and inspect every outcome if the group fails.

An edit reported as Applied can also be a no-op, such as removing an attribute that was absent. Do not infer a byte change from the status alone. On success, the change set describes which regions actually changed.

Inspect per-edit failure reasons

Use Outcomes: each item has the edit’s index, status and reason. The full program shows NotAttempted for the valid attribute change and Invalid for the attempted children of <br>. A valid request in a rejected transaction is not an independently committed change.

The documented statuses distinguish invalid input from an edit that cannot be expressed as HTML. Invalid means the operation or input does not fit the target. Failed means no enclosing rewrite could produce the intended tree when parsed again. NotAttempted identifies work that did not apply after the transaction stopped. The returned Document is absent on failure.

For a caller-facing error, show the reason with enough context to identify the requested operation. For application logic, branch on the status and Succeeded, not on the English reason string. Saved-edit replay has additional target-resolution outcomes, covered in the edit format; those are different from this example’s direct node-handle transaction.

All onehtml recipes