Skip to content

Latest commit

 

History

History
83 lines (62 loc) · 3.14 KB

README.md

File metadata and controls

83 lines (62 loc) · 3.14 KB
Raw

GitHub Actions NuGet Version NuGet Downloads

OpenMcdf

OpenMcdf is a fully .NET / C# library to manipulate Compound File Binary File Format files, also known as Structured Storage.

Compound files include multiple streams of information (document summary, user data) in a single container, and is used as the bases for many different file formats:

  • Microsoft Office (.doc, .xls, .ppt)
  • Windows thumbnails cache files (thumbs.db)
  • Outlook messages (.msg)
  • Visual Studio Solution Options (.suo)
  • Advanced Authoring Format (.aaf)

OpenMcdf v3 has a rewritten API and supports:

  • An idiomatic dotnet API and exception hierarchy
  • Fast and efficient enumeration and manipulation of storages and streams
  • File sizes up to 16 TB (using major format version 4 with 4096 byte sectors)
  • Transactions (i.e. commit and/or revert)
  • Consolidation (i.e. reclamation of space by removing free sectors)
  • Nullable attributes

Limitations:

  • No support for red-black tree balancing (directory entries are stored in a tree, but are not balanced. i.e. trees are "all-black")
  • No support for single writer, multiple readers

Getting started

To create a new compound file:

byte[] b = new byte[10000];

using var root = RootStorage.Create("test.cfb");
using CfbStream stream = root.CreateStream("MyStream");
stream.Write(b, 0, b.Length);

To open an Excel workbook (.xls) and access its main data stream:

using var root = RootStorage.OpenRead("report.xls");
using CfbStream workbookStream = root.OpenStream("Workbook");

To create or delete storages and streams:

using var root = RootStorage.Create("test.cfb");
root.CreateStorage("MyStorage");
root.CreateStream("MyStream");
root.Delete("MyStream");

For transacted storages, changes can either be committed or reverted:

using var root = RootStorage.Create("test.cfb", StorageModeFlags.Transacted);
root.Commit();
//
root.Revert();

A root storage can be consolidated to reduce its on-disk size:

root.Flush(consolidate: true);

Object Linking and Embedding (OLE) Property Set Data Structures

Support for reading and writing OLE Properties is available via the OpenMcdf.Ole package. However, the API is experimental and subject to change

OlePropertiesContainer co = new(stream);
foreach (OleProperty prop in co.Properties)
{
  ...
}

OpenMcdf runs happily on the Mono platform and multi-targets netstandard2.0 and net8.0 to maximize client compatibility and support modern dotnet features.