[Breaking change]: TarFile extraction accepts missing destination directories

[rzikm]

Description

System.Formats.Tar.TarFile extraction APIs no longer require the destination directory to exist before extraction begins. A nonempty archive creates the destination directory and any required parents while extracting its entries. Empty archives complete successfully without creating the destination directory.

This behavior now aligns TAR extraction with ZIP extraction. For more information, see dotnet/runtime#134845.

Version

Other (please put exact version in description textbox)

.NET 12 Preview 1.

Previous behavior

All TarFile.ExtractToDirectory and TarFile.ExtractToDirectoryAsync overloads required destinationDirectoryName to already exist. Passing a nonexistent destination path threw DirectoryNotFoundException, even when the archive itself contained entries that could create the directory.

using System.Formats.Tar;

TarFile.ExtractToDirectory("archive.tar", "output");
// Throws DirectoryNotFoundException when "output" does not exist.

New behavior

The extraction APIs create a missing destination directory and any missing parent directories as entries are extracted.

using System.Formats.Tar;

TarFile.ExtractToDirectory("archive.tar", "output");
// Extracts archive entries and creates "output" when needed.

An empty archive completes successfully but does not create a missing destination directory. Existing destination directories continue to be accepted regardless of the overwrite option, and file-overwrite behavior is unchanged.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

TAR extraction previously differed from ZIP extraction by requiring callers to create the destination directory themselves. Letting the existing per-entry extraction logic create required directories makes TAR extraction consistent with ZIP extraction while retaining lazy directory creation for empty archives.

Recommended action

Applications that expect TAR extraction to create output directories require no changes.

Applications that use a missing destination directory as an error condition must validate the directory before calling an extraction API:

if (!Directory.Exists(destinationDirectoryName))
{
    throw new DirectoryNotFoundException(destinationDirectoryName);
}

TarFile.ExtractToDirectory("archive.tar", destinationDirectoryName);

Do not rely on an empty archive to create its destination directory; create that directory explicitly if it is required after successful extraction.

Feature area

Core .NET libraries

Affected APIs

All overloads of the following APIs:

• System.Formats.Tar.TarFile.ExtractToDirectory
• System.Formats.Tar.TarFile.ExtractToDirectoryAsync