TarFile.ExtractToDirectoryAsync Method

Definition

Namespace:

System.Formats.Tar

Assembly:

System.Formats.Tar.dll

Overloads

Name	Description
ExtractToDirectoryAsync(String, String, Boolean, CancellationToken)	Asynchronously extracts the contents of a tar file into the specified directory.
ExtractToDirectoryAsync(Stream, String, Boolean, CancellationToken)	Asynchronously extracts the contents of a stream that represents a tar archive into the specified directory.

ExtractToDirectoryAsync(String, String, Boolean, CancellationToken)

Source:

TarFile.cs

Asynchronously extracts the contents of a tar file into the specified directory.

public static System.Threading.Tasks.Task ExtractToDirectoryAsync(string sourceFileName, string destinationDirectoryName, bool overwriteFiles, System.Threading.CancellationToken cancellationToken = default);

static member ExtractToDirectoryAsync : string * string * bool * System.Threading.CancellationToken -> System.Threading.Tasks.Task

Public Shared Function ExtractToDirectoryAsync (sourceFileName As String, destinationDirectoryName As String, overwriteFiles As Boolean, Optional cancellationToken As CancellationToken = Nothing) As Task

Parameters

sourceFileName

String

The path of the tar file to extract.

destinationDirectoryName

String

The path of the destination directory where the filesystem entries should be extracted. In .NET 11 and earlier versions, the directory must already exist. In .NET 12 and later versions, missing destination and parent directories are created as needed when entries are extracted. An empty archive does not create any directories.

overwriteFiles

Boolean

true to overwrite files and directories in destinationDirectoryName; false to avoid overwriting, and throw if any files or directories are found with existing names.

cancellationToken

CancellationToken

The token to monitor for cancellation requests. The default value is None.

Returns

Task

A task that represents the asynchronous extraction operation.

Exceptions

ArgumentNullException

sourceFileName or destinationDirectoryName is null.

DirectoryNotFoundException

.NET 11 and earlier versions: The destinationDirectoryName directory does not exist.

FileNotFoundException

The sourceFileName file path is not found.

UnauthorizedAccessException

Permissions are insufficient.

ArgumentException

Extracting one of the tar entries would have resulted in a file outside the specified destination directory.

-or-

sourceFileName or destinationDirectoryName is empty.

InvalidDataException

.NET 11 and later versions only: An entry's checksum is invalid.

IOException

An I/O exception occurred.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

Remarks

Warning

This method must not be used to extract untrusted archives. It doesn't enforce any size limits, entry count limits, or other policies needed for safe extraction of untrusted archives. For more information on safely extracting archives from untrusted sources, see Best practices for using zip and tar archives.

In .NET 11 and earlier versions, the directory specified by destinationDirectoryName must already exist. If it doesn't exist, this method throws an DirectoryNotFoundException, even if the archive is empty.

In .NET 12 and later versions, the destination directory can already exist. Missing destination and parent directories are created as needed when entries are extracted. An empty archive doesn't create any directories.

If a symbolic link or junction in the tar archive results in a file being extracted outside the specified destinationDirectoryName, an IOException is thrown to ensure extraction remains within the same directory.

If destinationDirectoryName or any of its parent directories is a pre-existing junction or symbolic link, the link is followed and the extraction writes to the final target folder.

Files of type BlockDevice, CharacterDevice, or Fifo can only be extracted in Unix platforms.

Elevation is required to extract a BlockDevice or CharacterDevice to disk.

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by ExtractToDirectory(String, String, Boolean).

ExtractToDirectoryAsync(Stream, String, Boolean, CancellationToken)

Source:

TarFile.cs

Asynchronously extracts the contents of a stream that represents a tar archive into the specified directory.

public static System.Threading.Tasks.Task ExtractToDirectoryAsync(System.IO.Stream source, string destinationDirectoryName, bool overwriteFiles, System.Threading.CancellationToken cancellationToken = default);

static member ExtractToDirectoryAsync : System.IO.Stream * string * bool * System.Threading.CancellationToken -> System.Threading.Tasks.Task

Public Shared Function ExtractToDirectoryAsync (source As Stream, destinationDirectoryName As String, overwriteFiles As Boolean, Optional cancellationToken As CancellationToken = Nothing) As Task

Parameters

source

Stream

The stream containing the tar archive.

destinationDirectoryName

String

The path of the destination directory where the filesystem entries should be extracted. In .NET 11 and earlier versions, the directory must already exist. In .NET 12 and later versions, missing destination and parent directories are created as needed when entries are extracted. An empty archive does not create any directories.

overwriteFiles

Boolean

true to overwrite files and directories in destinationDirectoryName; false to avoid overwriting, and throw if any files or directories are found with existing names.

cancellationToken

CancellationToken

The token to monitor for cancellation requests. The default value is None.

Returns

Task

A task that represents the asynchronous extraction operation.

Exceptions

ArgumentNullException

source or destinationDirectoryName is null.

DirectoryNotFoundException

.NET 11 and earlier versions: The destinationDirectoryName directory does not exist.

UnauthorizedAccessException

Permissions are insufficient.

ArgumentException

Extracting one of the tar entries would have resulted in a file outside the specified destination directory.

-or-

destinationDirectoryName is empty.

-or-

source does not support reading.

InvalidDataException

.NET 11 and later versions only: An entry's checksum is invalid.

IOException

An I/O exception occurred.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.

Remarks

Warning

This method must not be used to extract untrusted archives. It doesn't enforce any size limits, entry count limits, or other policies needed for safe extraction of untrusted archives. For more information on safely extracting archives from untrusted sources, see Best practices for using zip and tar archives.

In .NET 11 and earlier versions, the directory specified by destinationDirectoryName must already exist. If it doesn't exist, this method throws an DirectoryNotFoundException, even if the archive is empty.

In .NET 12 and later versions, the destination directory can already exist. Missing destination and parent directories are created as needed when entries are extracted. An empty archive doesn't create any directories.

If a symbolic link or junction in the tar archive results in a file being extracted outside the specified destinationDirectoryName, an IOException is thrown to ensure extraction remains within the same directory.

If destinationDirectoryName or any of its parent directories is a pre-existing junction or symbolic link, the link is followed and the extraction writes to the final target folder.

Files of type BlockDevice, CharacterDevice, or Fifo can only be extracted in Unix platforms.

Elevation is required to extract a BlockDevice or CharacterDevice to disk.

This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as ArgumentException, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by ExtractToDirectory(Stream, String, Boolean).