Skip to content

known limitations

Jump to bottom
github-actions[bot] edited this page Nov 8, 2026 · 18 revisions

Known Limitations

XISOSharp aims to be the most complete XISO/XDVDFS library, not every Xbox container. This page lists deliberate boundaries and current workarounds.

Scope

XISO/XDVDFS, Redump full-disc images, split ISO, CISO/CSO, CCI/CCIM, ZAR, read-only GOD/SVOD sector input, GOD and single-file XBLA/XBLIG header title metadata, XBLA/XBLIG STFS package listing/extraction and SHA-1 hash-tree validation, Xbox 360 XDBF/XSRC title metadata, XBE logo/title/save image extraction, and XBE/XEX read-only metadata are in scope.

Deliberately out of scope:

  • STFS/CON/LIVE/PIRS writing, package rebuild and re-signing. Read-only GOD/SVOD input is supported through StfsSharp.GodVolume, and single-file XBLA/XBLIG package listing/extraction through StfsSharp.StfsPackage; STFS writes stay out of scope. StfsSharp.StfsPackage.Validate verifies the per-block SHA-1 hash tree (level-0/1/2 tables, top hash and header hash), but package signatures are not verified and the reader accepts XBLA/XBLIG/Community Game content types (not saves, profiles or DLC packages). XISOSharp 1.9.0 removed the 1.x compatibility facades: reference the StfsSharp package directly for these types.
  • CHD containers
  • XEX decryption or XBE editing
  • FUSE/Dokan mounting (see SimpleXisoDrive)
  • direct optical-drive reading (implement IBlockDevice)
  • Python bindings / a native ABI
  • executable signature verification (owner decision 2026-11-01; --validate stays structural)
  • ZIP input (XISO Studio already ships SharpCompress)
  • XGD-shaped synthesis from a folder / an XGD header writer (cannot produce a bootable disc; --prepend-sectors + rebuild cover real workflows)
  • a dotnet tool package (removed after 1.5.0; the CLI ships only in the six RID bundles)

Concurrency

XisoWriter.CreateXiso/PackFromDirectory resolve a local source to absolute host paths, keep progress counters per operation, and take no process-wide lock. Concurrent creates run independently and never change the process working directory. A caller-supplied inRoot without host paths is resolved once against the caller's CWD, so it is CWD-free too.

XisoReader.Extract/UnpackImage also never change the process working directory: extraction resolves entry paths through a LocalFilesystem rooted at the output directory, and concurrent extracts into different destinations stay independent. XisoReader.UnpackImage(..., IFilesystem) remains the way to target a custom store.

Create sources can also be virtual: ISourceFilesystem (and the MemoryFilesystem source overloads) packs a custom store without host paths. Implementations need not be thread-safe; enumeration and reads are sequential. Per-call log sinks (XisoLogScope) are AsyncLocal-based, so they isolate concurrent operations without changing the static Logger facade.

Windows paths and names

The CLI and GUI manifests opt into longPathAware, and extraction rejects or sanitizes path separators, drive-relative colons, trailing dots/spaces and DOS device names (CON, NUL, COM1…). --name-policy reject|sanitize|skip (and UnpackOptions.NamePolicy) chooses fail-fast, collision-safe renaming, or skipping for a recovery run. The OS must still have long paths enabled (LongPathsEnabled) on Windows 10 1607+.

Archival metadata

  • XRD Redump metadata generation is not implemented. XboxKit 0.7's own XRD writer is a stub (zeroed hashes, TODO certificates), so there is no verified oracle to port.
  • Redump rebuild needs the original video partition and filler/seed (or ZAR sidecar); it cannot invent missing disc bytes.
  • verify-hashes validates the per-file .hash sidecar and detects MD5, SHA-1 and SHA-256 digests; file-hashes generates the sidecar for any supported container. verify-dat matches whole images against a Redump-style XML DAT by size and MD5/SHA-1/CRC32; no DAT source is bundled, so callers supply their own file.

Compression

  • CCI levels 0..9 use the fast LZ4 block encoder; levels 10..12 use CCISharp's managed LZ4-HC encoder (12 = highest effort). Output is spec-valid and interoperable; HC byte parity with libCCI/Repackinator is best-effort, not a guarantee.
  • Single-file CCI --jobs 1..64 compresses sectors in parallel with byte-identical output; batch --jobs still runs conversions in parallel.
  • CISO v2 is byte-identical to modern xdvdfs compress; CISO v1 (DEFLATE) is supported for reading and writing but is legacy.
  • In-place --repair, --copy-in, --set-filetime, -r (rewrite) and split refuse compressed, GOD, STFS and split containers; decompress/join/extract first.

Platforms and support

  • The library targets net8.0, net9.0 and net10.0. .NET 9 is EOL (May 2026) and .NET 8 is EOL (10 November 2026); both remain supported compatibility targets in 2.x (built and tested on every release). net10.0 is the LTS target going forward.
  • The test suite runs on Windows, Linux and macOS. The WPF XISOSharpTester harness only runs on Windows (it builds everywhere).
  • The per-file size field is 32-bit, so a single file cannot exceed ~4 GiB. Plain-ISO split defaults to 0xFF000000 (4 GiB - 16 MiB) so parts fit FATX; CISO/CCI keep 0xffbf6000 as their xdvdfs-compatible compression default.
  • Sparse output is best-effort: NTFS/Unix mark pre-sized files sparse and skip zero chunks, but FAT/exFAT and file systems without sparse support fall back to dense allocation. The written bytes and image length are unchanged.

Distribution

  • Release bundles and the NuGet library are built by CI with an SBOM and build provenance. Authenticode signing, macOS notarization and NuGet author signing are implemented but disabled by default: enable them with the repository variables/secrets listed in Building. Unsigned builds remain the default and are fully supported.
  • Shell completions and the xisosharp(1) man page ship in the docs tree (docs/completions, docs/man); the six RID zips keep their five-file layout and do not embed them.
  • winget/Scoop/Homebrew manifests are generated from release assets. winget and Homebrew still require submission to their upstream repositories (or a local manifest/cask install); the checked-in Scoop bucket works directly.
  • The container image contains the CLI only (no GUI, no .NET SDK).
  • The CLI ships only through GitHub releases (no NuGet package). The release zips are framework-dependent (need the .NET 10 runtime); the self-contained single-file builds come from publish-cli.ps1 / publish-gui.ps1.

Clone this wiki locally