Skip to content
Office Oxide

C# / .NET Office ライブラリ — クイックスタート

OfficeOxide は Rust の office_oxide ライブラリの .NET バインディングです。.NET アプリに高速かつアロケーションを抑えた DOCX / XLSX / PPTX / DOC / XLS / PPT の解析・変換・編集機能を提供します — 内部では AOT 対応の LibraryImport P/Invoke を使用しています。

インストール

dotnet add package OfficeOxide --version 0.1.0

.NET 8 または .NET 10 が必要です。NuGet パッケージは runtimes/<rid>/native/ 配下に win-x64、linux-x64、linux-arm64、osx-x64、osx-arm64 の prebuilt ネイティブライブラリを同梱します。dotnet publish で適切な物がバイナリの隣に自動配置されます。

ドキュメントを読む

using OfficeOxide;

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

コア API

Document は読み取り専用ハンドル。using で破棄してネイティブメモリを解放してください。

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");              // 保存先は拡張子から推定

ブロッキング IO 用の非同期ラッパー:

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

バイトから開く（一時ファイル不要）:

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

format は "docx"、"xlsx"、"pptx"、"doc"、"xls"、"ppt" のいずれか。

ワンショット呼び出し用の静的ヘルパー:

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
Console.WriteLine(Document.Version);                // "0.1.0"

編集

編集は変更されていない OPC パーツ（画像、グラフ、リレーションシップ）をすべて温存します。DOCX、XLSX、PPTX のみ。

using OfficeOxide;

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

ReplaceText は置換件数を返します（XLSX では 0 — SetCell を使ってください）。

DOCX / PPTX のテキスト置換

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 セルの設定（4 つのオーバーロード）

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

wb.SetCell(0u, "A1", "Total");        // 文字列オーバーロード
wb.SetCell(0u, "B1", 42.5);           // double オーバーロード
wb.SetCell(0u, "C1", true);           // bool オーバーロード
wb.SetCellEmpty(0u, "D1");            // セルをクリア

wb.Save("budget.xlsx");

sheetIndex は 0 始まり、cellRef は標準的な表計算記法（A1、AA12）。

フォーマット非依存の IR

ToIrJson() は Rust の DocumentIR 形状に合致する JSON 文字列を返します:

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());
}

バイト列ベースのパイプライン

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());

レガシーフォーマット

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

AOT / トリミング

プロジェクトは IsAotCompatible=true と IsTrimmable=true を設定しています。すべての P/Invoke は LibraryImport ソースジェネレータを使うので、dotnet publish -c Release -p:PublishAot=true で単一の自己完結型実行可能ファイルが得られます。

エラー

失敗は型付きの Code プロパティを持つ OfficeOxideException を送出します:

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

破棄済みハンドルへのメソッド呼び出しは ObjectDisposedException を送出します。

Code 名前 意味
0 Ok 成功
1 InvalidArg null / 空 / 不正なフォーマット文字列
2 Io ファイルシステムエラー
3 Parse 壊れたドキュメント
4 Extraction パースは成功したがレンダリングが失敗
5 Internal バグ — issue を上げてください
6 Unsupported 拡張子/機能が未対応

トラブルシューティング

症状 対処
DllNotFoundException: office_oxide ネイティブライブラリがバイナリ隣にコピーされていません。素の dotnet build ではなく dotnet publish を実行してください。
Windows で BadImageFormatException CPU アーキ不一致 — 適切な win-x64 または win-arm64 ビルドをデプロイ。
.doc で OfficeOxideException のコード Unsupported 拡張子が小文字か、FromBytes で明示的にフォーマット指定。
トリミング後にシンボルが欠落 <TrimmerRootAssembly> に OfficeOxide を追加。
macOS「開発元未確認のため開けません」 xattr -d com.apple.quarantine /path/to/liboffice_oxide.dylib を実行するかバンドルに署名。

関連項目