Recursive AI

Create an ISO 9660 image in C#

OneArchive is a free, open-source archive and compression library for .NET from Recursive AI: archives (zip, tar, 7z, RAR 5, cpio, ar, ISO) in RecursiveAI.OneArchive, codecs (zlib, gzip, xz, Zstandard, Brotli) in RecursiveAI.OneCompress. MIT or Apache-2.0, no native dependencies.

An ISO image stores a disc’s file structure in one file. Create a data image from a directory; this writer does not create boot catalogs or hybrid partition tables.

Terminal
dotnet add package RecursiveAI.OneArchive

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

C#
using RecursiveAI.OneArchive;
 
Directory.CreateDirectory("files");
File.WriteAllText("files/hello.txt", "Hello from ISO!\n");
Archive.Create("sample.iso").Add("files", "").Save();
Console.WriteLine("Created sample.iso");

The empty name "" in Add("files", "") puts the folder’s contents at the image root, without a wrapping files directory.

Text
Created sample.iso

Unzip the example, then dotnet run.

The full program

The program creates files/hello.txt containing Hello from ISO! followed by a newline, writes sample.iso and reads the file back from the image. It replaces these sample files on each run.

The defaults enable Joliet (Unicode filenames) and Rock Ridge (long names and Unix metadata).

C#
using RecursiveAI.OneArchive;
 
Directory.CreateDirectory("files");
File.WriteAllText("files/hello.txt", "Hello from ISO!\n");
Archive.Create("sample.iso").Add("files", "").Save();
Console.WriteLine("Created sample.iso");
 
using var archive = Archive.Open("sample.iso");
foreach (var entry in archive.Entries)
{
    if (entry.Kind != ArchiveEntryKind.File) continue;
    using var content = archive.OpenEntry(entry);
    using var reader = new StreamReader(content);
    string text = reader.ReadToEnd();
    Console.WriteLine($"{entry.Name}: {entry.Size} bytes");
    Console.Write(text);
    Console.WriteLine($"Text matches: {text == "Hello from ISO!\n"}");
}

dotnet run prints:

Text
Created sample.iso
hello.txt: 16 bytes
Hello from ISO!
Text matches: True

A missing source raises FileNotFoundException; links, devices and FIFOs without Rock Ridge raise ArchiveUnsupportedException.

Variations

Create a plain level-1 image without Joliet or Rock Ridge, and set its volume label.

C#
using RecursiveAI.OneArchive;
using RecursiveAI.OneArchive.Iso;
 
Directory.CreateDirectory("files");
File.WriteAllText("files/hello.txt", "Hello from ISO!\n");
var options = new ArchiveCreateOptions
{
    Iso = new IsoWriterOptions
    {
        VolumeId = "EXAMPLE",
        Level = 1,
        Joliet = false,
        RockRidge = false
    }
};
Archive.Create("plain.iso", options).Add("files", "").Save();
using var archive = Archive.Open("plain.iso");
foreach (var entry in archive.Entries)
    if (entry.Kind == ArchiveEntryKind.File)
        Console.WriteLine(entry.Name);
Text
HELLO.TXT

The short answer

To create an ISO 9660 image in C#, install RecursiveAI.OneArchive and call Archive.Create("sample.iso").Add("files", "").Save(). The extension selects the ISO writer. The empty entry name puts the directory’s contents at the image root rather than inside a files directory. The example creates its source text itself, so it needs no downloaded sample or disc device.

The writer defaults to interchange level 3 with Joliet and Rock Ridge enabled. It creates a data image. It does not write boot catalogs or hybrid partition tables, so this example is not a bootable operating-system installer.

How to make an ISO image file from a folder?

First prepare a directory containing only the files you want in the image. Pass that directory to Add, then call Save once to write the output. For an existing folder, remove the sample’s Directory.CreateDirectory and File.WriteAllText lines and change the Add path. Keep the destination image outside the input folder so a later run does not accidentally include the previous image.

The full program reopens the finished file through Archive.Open, lists its file entries and reads their contents. This checks the image as a container, rather than just checking that an output file exists. In your application, compare bytes for binary files instead of reading them through StreamReader.

For more control, set ArchiveCreateOptions.Iso to an IsoWriterOptions object. The variation changes the volume ID, selects level 1 and disables both filename extensions. Its output shows why those options matter: the plain identifier is HELLO.TXT, whereas the default reader returns hello.txt from the image created with the defaults.

The writer cannot finalize the layout until it knows every entry name. It spools file content in memory up to MaxMemoryBuffer, which defaults to 64 MiB, then uses a temporary file. Budget temporary storage as well as the destination’s disk space when creating large images. The output stream itself does not have to support seeking.

What is the ISO 9660 standard?

ISO 9660 specifies volume and file structures for CD-ROM information interchange. An ISO image keeps that structure in a file. In this writer, the interchange level controls the plain names; Joliet and Rock Ridge carry additional naming and metadata information. A reader’s selected hierarchy determines which names it exposes.

OneArchive’s automatic reader chooses the primary hierarchy with Rock Ridge when available, otherwise Joliet when present, otherwise the plain primary hierarchy. The ISO documentation describes these choices. Do not assume every reader displays the same spelling simply because it can open the image.

Names cut to the selected plain level that collide receive a three-digit counter in write order. Joliet names are cut to 64 UTF-16 units while keeping a short extension, and forbidden characters become underscores. Symbolic links, devices and FIFOs require Rock Ridge; the writer refuses them when that extension is disabled. Files of 4 GiB or more require level 3 and are written in multiple extents. These rules make a data image useful without implying that arbitrary filesystem metadata or boot behavior will survive unchanged.

All onearchive recipes