Skip to content
Office Oxide

C#/.NET-Bibliothek für Office — Schnellstart

OfficeOxide ist die .NET-Bindung für die Rust-Library office_oxide. Sie bietet .NET-Anwendungen schnelles, allokationsschonendes Parsen, Konvertieren und Bearbeiten von DOCX / XLSX / PPTX / DOC / XLS / PPT — unter der Haube AOT-kompatibles LibraryImport-P/Invoke.

Installation

dotnet add package OfficeOxide --version 0.1.0

Benötigt .NET 8 oder .NET 10. Das NuGet-Paket bringt vorgebaute native Libraries für win-x64, linux-x64, linux-arm64, osx-x64, osx-arm64 unter runtimes/<rid>/native/ mit. dotnet publish legt die passende automatisch neben deine Binary.

Ein Dokument lesen

using OfficeOxide;

using var doc = Document.Open("report.docx");
Console.WriteLine(doc.PlainText());

Kern-API

Document ist das Read-only-Handle; mit using disposen, damit der native Speicher freigegeben wird.

using OfficeOxide;

using var doc = Document.Open("file.xlsx");

Console.WriteLine(doc.Format);        // "xlsx"
Console.WriteLine(doc.PlainText());
Console.WriteLine(doc.ToMarkdown());
Console.WriteLine(doc.ToHtml());
Console.WriteLine(doc.ToIrJson());

doc.SaveAs("file.docx");              // Zielformat ergibt sich aus der Erweiterung

Async-Wrapper für blockierendes IO:

using var doc = await Document.OpenAsync("huge.pptx", ct);

Aus Bytes öffnen (ohne Tempdatei):

byte[] data = File.ReadAllBytes("report.docx");
using var doc = Document.FromBytes(data, "docx");

format muss "docx", "xlsx", "pptx", "doc", "xls" oder "ppt" sein.

Statische Helper für Einzelaufrufe:

string text = OfficeOxide.ExtractText("file.docx");
string md   = OfficeOxide.ToMarkdown("file.pptx");
string html = OfficeOxide.ToHtml("file.xlsx");

string? fmt = Document.DetectFormat("mystery.bin"); // null, wenn nicht unterstützt
Console.WriteLine(Document.Version);                // "0.1.0"

Bearbeiten

Beim Speichern bleiben alle unveränderten OPC-Teile (Bilder, Diagramme, Beziehungen) erhalten. Nur DOCX, XLSX und PPTX.

using OfficeOxide;

using var ed = EditableDocument.Open("template.docx");
long n = ed.ReplaceText("{{name}}", "Alice");
Console.WriteLine($"{n} Ersetzungen");
ed.Save("out.docx");

ReplaceText liefert die Anzahl Ersetzungen (auf XLSX 0 — dort SetCell benutzen).

Text in DOCX / PPTX ersetzen

using var ed = EditableDocument.Open("slides.pptx");
ed.ReplaceText("Q3", "Q4");
ed.ReplaceText("2024", "2025");

byte[] bytes = ed.SaveToBytes();
File.WriteAllBytes("slides_q4.pptx", bytes);

XLSX-Zellen setzen (vier Overloads)

using var wb = EditableDocument.Open("budget.xlsx");

wb.SetCell(0u, "A1", "Total");        // String-Overload
wb.SetCell(0u, "B1", 42.5);           // double-Overload
wb.SetCell(0u, "C1", true);           // bool-Overload
wb.SetCellEmpty(0u, "D1");            // Zelle leeren

wb.Save("budget.xlsx");

sheetIndex ist nullbasiert; cellRef folgt der Standard-Tabellen-Notation (A1, AA12).

Formatunabhängige IR

ToIrJson() liefert einen JSON-String, der der Rust-DocumentIR-Form entspricht:

using System.Text.Json;

using var doc = Document.Open("report.docx");
string json = doc.ToIrJson();

using var ir = JsonDocument.Parse(json);
foreach (var section in ir.RootElement.GetProperty("sections").EnumerateArray())
{
    if (section.TryGetProperty("title", out var t) && t.ValueKind != JsonValueKind.Null)
        Console.WriteLine(t.GetString());
}

Bytes-Pipelines

using var http = new HttpClient();
byte[] data = await http.GetByteArrayAsync("https://example.com/file.docx");
using var doc = Document.FromBytes(data, "docx");
Console.WriteLine(doc.ToMarkdown());

Altformate

using var legacy = Document.Open("old.xls");
legacy.SaveAs("modern.xlsx");

AOT / Trimming

Das Projekt setzt IsAotCompatible=true und IsTrimmable=true. Alle P/Invokes nutzen den LibraryImport-Source-Generator; dotnet publish -c Release -p:PublishAot=true ergibt eine einzige Self-Contained-Executable.

Fehler

Fehler werfen OfficeOxideException mit typisierter Code-Eigenschaft:

try
{
    using var doc = Document.Open("missing.docx");
}
catch (OfficeOxideException ex)
{
    Console.WriteLine($"code={ex.Code} op={ex.Operation}");
}

Methodenaufrufe auf einem schon disposeten Handle werfen ObjectDisposedException.

Code Name Bedeutung
0 Ok Erfolg
1 InvalidArg null / leer / falscher Format-String
2 Io Dateisystem-Fehler
3 Parse beschädigtes Dokument
4 Extraction Parsing OK, aber Rendering scheiterte
5 Internal Bug — bitte Issue eröffnen
6 Unsupported Erweiterung/Feature nicht unterstützt

Fehlersuche

Symptom Lösung
DllNotFoundException: office_oxide Native Lib wurde nicht neben die Binary kopiert. dotnet publish statt nacktes dotnet build ausführen.
BadImageFormatException unter Windows Architektur passt nicht — passenden win-x64- oder win-arm64-Build deployen.
OfficeOxideException mit Code Unsupported bei .doc Erweiterung muss klein geschrieben sein, oder Format explizit über FromBytes übergeben.
Nach Trimming fehlen Symbole OfficeOxide in <TrimmerRootAssembly> aufnehmen.
macOS „kann nicht geöffnet werden, da Entwickler nicht verifiziert" xattr -d com.apple.quarantine /path/to/liboffice_oxide.dylib ausführen oder das Bundle signieren.

Siehe auch