Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Oct 1, 2026 · 6 revisions

XISOSharp — Documentation

CI Docs Docsify Pages Wiki sync .NET NuGet GitHub stars GitHub contributors Last commit License

XISOSharp is a pure C# implementation of extract-xiso build 202609111233 — the tool and library for creating, extracting, listing, auditing, and rewriting Xbox ISO (XISO / XDVDFS) disc images. It is a direct, byte-identical port of the original C codebase into idiomatic managed C# — no native dependencies, no P/Invoke.

This documentation set is published twice from the same sources and covers the CLI, the .NET library API, the XISO on-disk format, Xbox disc formats (XGD1/XGD2/XGD3/Hybrid, Redump images), archival workflows, and xdvdfs parity:

  • GitHub Pages — rendered with Docsify; the fixed left sidebar comes from _sidebar.md, served by index.html (pages.yml deploys docs/).
  • GitHub Wiki — wiki.yml runs sync-wiki.ps1, which copies every page, generates Home.md from this index, and builds the wiki side menu _Sidebar.md from the same _sidebar.md, so both targets always share one navigation.

Both side menus list the same pages; relative page links work in either renderer.

Table of contents

Left menu: the wiki sidebar is the canonical navigation for Pages and the wiki. The table below mirrors it for plain GitHub rendering.

User guide

Page What it covers
Getting Started Installation, first extract/create/list, requirements
CLI Reference Every command, flag, mode, exit code, and batch behavior (incl. archival & xdvdfs verbs)
Validation validate command and --validate* flags
Redump & Disc Layouts XGD offsets (incl. hybrid 0x89D80000), video partitions, --skip-sectors / --prepend-sectors
Archival Workflows Redump lossless pipeline: --video / --random / --seed / --wipe / --trim / --petrify / --update / --zar / --all / --best / --compress / rebuild / --security-sectors
Build-Image & Image-Spec Ordered wax remapping (host/**:image/{1}, !negation, {n} captures), --dry-run, xdvdfs.toml
Compression (CISO) compress/decompress (CISO DEFLATE v1 + LZ4 v2, align 0/1/2), BlockDevice stack
Checksums SHA3-256 image checksum (checksum) vs per-file MD5/SHA-256 (--md5/--sha256)
XISO Format On-disk format: header, directory entries, AVL tree, ECMA-119, empty-dir 0x0000 sentinel
FAQ Frequently asked questions

Library API reference

Page What it covers
Library Overview Architecture, packages, error handling, quick samples
XisoReader Read/extract/list/audit/hash/checksum APIs (+ IBlockDevice overloads)
XisoWriter Create/rewrite + remap (build-image) APIs
Utilities & Types Logger, GlobMatcher/WaxGlob, AvlTree, Constants, XisoRanges, XboxPrng, SecuritySectors, BlockDevice, records, enums, exceptions
xdvdfs Compatibility Block-device abstraction, CISO parity, remap semantics

Development

Page What it covers
Building SDK requirements, build/publish, CI pipeline
Testing Test suite, TestData, reference-tool comparison, benchmarks, BattleTests
Contributing Contribution workflow, code style, PR guidelines
Troubleshooting Common errors and how to resolve them
Release Notes What changed in each release

Feature highlights

  • Create XISO images from a directory, with glob-based exclusion (-X via GlobMatcher/WaxGlob)
  • Extract full images, or single files/directories with --copy-out / --unpack (auto llCompat); resume interrupted runs with --skip-existing (skip: <path>); patch single files back in with --copy-in (keeps .old backup)
  • List (-l), recursive tree (-t), volume info (-i), hash (--md5 / --sha256), per-image SHA3-256 checksum, XEX2 (--xex-info) and XBE (--xbe-info) executable info
  • Rewrite images into an optimized AVL layout (-r) + validate (validate / --validate*); outputs colliding with their inputs are refused (input==output guard)
  • Audit (-V) deep integrity: header (5 offsets), tag 31337, tree cycles, sector bounds, reserved 0x48, empty 0x0000
  • Repair (--repair) fixable issues in place (reserved bits, tag, separators; .old backup, --dry-run) and salvage (--salvage) rebuilds of damaged images into fresh audited .iso — no reference tool does either
  • Disc coverage — RAW 0x0, GLOBAL/XGD2 0x0FD90000, XGD3 0x02080000, Hybrid 0x89D80000, XGD1 0x18300000 (native) + arbitrary --skip-sectors/--prepend-sectors
  • Redump archival (XboxKit parity): --video, --random (filler), --seed (XGD1 PRNG brute-force), --wipe, --trim, --petrify (skeleton + SHA-1), --update (XGD3 su…), --zar (ZArchive/zstd, --jobs/--policy), --security-sectors <sectors.txt> (rebuild only), aliases --all/--best/--compress, verb rebuild for lossless Redump ↔ XISO
  • xdvdfs parity: build-image ordered host/**:image/{0|1} (! + {n} captures, xdvdfs.toml, --dry-run, \: colon escaping), image-spec from, CISO compress/cso/decompress/uncso/decso (DEFLATE v1 0x80000000 + LZ4 v2, align 0/1/2, --ciso-level/--ciso-version/--ciso-split) with CisoBlockDevice random-access, split/join/joinsplit FATX parts, IBlockDevice (File/Memory/Offset/Ciso)
  • Automatic .xbe media-enable patching (Boyer–Moore E8 CA FD FF FF 85 C0 7D → EB)
  • Async APIs, IProgress<ProgressInfo> (FileCount/DirCount/DirAdded/FileAdded/FileProgress/FinishedPacking, with FileAdded also per written file and per-chunk FileProgress in extract mode), CancellationToken throughout
  • Multi-targets .NET 8, .NET 9, and .NET 10; strong-named; trim/AOT compatible; left side menu on Pages and the GitHub Wiki

Quick start

# Extract an ISO to a directory
XISOSharp -d output_dir game.iso

# Create an ISO from a directory
XISOSharp -c source_dir

# List contents
XISOSharp -l game.iso
// Library usage
using XISOSharp;

int result = XisoReader.Extract("game.iso", "output_directory", llCompat: false);
int result = XisoWriter.CreateXiso("source_directory", "output_directory",
    inRoot: null, sourceStream: null, out _, inName: "game.iso", progressCallback: null);

See Getting Started for details.

Project layout

Project Description
XISOSharp Class library (NuGet package XISOSharp) — complete read/write engine
XISOSharp.Cli Command-line tool XISOSharp (extract-xiso-compatible flags)
XISOSharp.Tests xUnit test suite
XISOSharp.Benchmarks BenchmarkDotNet benchmarks (AVL tree, Boyer–Moore, sector math)
XISOSharpTester WPF GUI for batch regression testing against the reference C tool
References/ Reference sources: extract-xiso build 202609111233 (extract-xiso.c, same internal version 2.7.1, empty-dir rewrite fix), xdvdfs 0.8.3, XboxKit 0.7
TestData/ Fixtures used by tests and the output-comparison scripts
XISOSharp.Tests/Fixtures/ Checked-in test_fixture.iso snapshot reference (see Testing)

License

MIT — see LICENSE.

Clone this wiki locally