Edit

Share via

ZipFile.OpenAsync Method

Definition

Namespace:
System.IO.Compression
Assemblies:
netstandard.dll, System.IO.Compression.ZipFile.dll

Overloads

OpenAsync(String, ZipArchiveMode, CancellationToken)

Asynchronously opens a ZipArchive on the specified archiveFileName in the specified ZipArchiveMode mode.
OpenAsync(String, ZipArchiveMode, Encoding, CancellationToken)

Asynchronously opens a ZipArchive on the specified archiveFileName in the specified ZipArchiveMode mode.

OpenAsync(String, ZipArchiveMode, CancellationToken)

Source:
ZipFile.Create.Async.cs

Asynchronously opens a ZipArchive on the specified archiveFileName in the specified ZipArchiveMode mode.

public static System.Threading.Tasks.Task<System.IO.Compression.ZipArchive> OpenAsync(string archiveFileName, System.IO.Compression.ZipArchiveMode mode, System.Threading.CancellationToken cancellationToken = default);
static member OpenAsync : string * System.IO.Compression.ZipArchiveMode * System.Threading.CancellationToken -> System.Threading.Tasks.Task<System.IO.Compression.ZipArchive>
Public Shared Function OpenAsync (archiveFileName As String, mode As ZipArchiveMode, Optional cancellationToken As CancellationToken = Nothing) As Task(Of ZipArchive)

Parameters

archiveFileName
String

The path on the filesystem to open the archive on.

mode
ZipArchiveMode

One of the enumeration values that specifies the actions that are allowed on the entries in the opened archive.

cancellationToken
CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<ZipArchive>

Exceptions

ArgumentException

archiveFileName is a zero-length string, contains only whitespace, or contains one or more invalid characters as defined by InvalidPathChars.

ArgumentNullException

archiveFileName is null.

PathTooLongException

archiveFileName exceeds the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.

DirectoryNotFoundException

The specified archiveFileName is invalid, (for example, it is on an unmapped drive).

IOException

An unspecified I/O error occurred while opening the file.

UnauthorizedAccessException

archiveFileName specified a directory.

-or-

The caller does not have the required permission.

ArgumentOutOfRangeException

mode specified an invalid value.

FileNotFoundException

The file specified in archiveFileName was not found.

NotSupportedException

archiveFileName is in an invalid format.

InvalidDataException

The specified file could not be interpreted as a zip file.

-or-

mode is Update and an entry is missing from the archive or is corrupt and cannot be read.

-or-

mode is Update and an entry is too large to fit into memory.

OperationCanceledException

An asynchronous operation is cancelled.

Remarks

For archiveFileName:

The path is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory.

For mode:

If Read is specified, the file is opened with System.IO.FileMode.Open, and will throw a FileNotFoundException if the file does not exist.

If Create is specified, the file is opened with System.IO.FileMode.CreateNew, and will throw a System.IO.IOException if the file already exists.

If Update is specified, the file is opened with System.IO.FileMode.OpenOrCreate.

If the file exists and is a zip file, its entries will become accessible and can be modified, and new entries can be created.

If the file exists and is not a zip file, a InvalidDataException is thrown.

If the file exists and is empty or does not exist, a new zip file will be created.

Creating a zip file with the Create mode is more efficient when creating a new zip file.

Applies to

OpenAsync(String, ZipArchiveMode, Encoding, CancellationToken)

Source:
ZipFile.Create.cs

Asynchronously opens a ZipArchive on the specified archiveFileName in the specified ZipArchiveMode mode.

public static System.Threading.Tasks.Task<System.IO.Compression.ZipArchive> OpenAsync(string archiveFileName, System.IO.Compression.ZipArchiveMode mode, System.Text.Encoding? entryNameEncoding, System.Threading.CancellationToken cancellationToken = default);
static member OpenAsync : string * System.IO.Compression.ZipArchiveMode * System.Text.Encoding * System.Threading.CancellationToken -> System.Threading.Tasks.Task<System.IO.Compression.ZipArchive>
Public Shared Function OpenAsync (archiveFileName As String, mode As ZipArchiveMode, entryNameEncoding As Encoding, Optional cancellationToken As CancellationToken = Nothing) As Task(Of ZipArchive)

Parameters

archiveFileName
String

The path on the filesystem to open the archive on.

mode
ZipArchiveMode

One of the enumeration values that specifies the actions that are allowed on the entries in the opened archive.

entryNameEncoding
Encoding

The encoding to use when reading or writing entry names and comments in this ZipArchive.

cancellationToken
CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<ZipArchive>

Exceptions

ArgumentException

archiveFileName is a zero-length string, contains only whitespace, or contains one or more invalid characters as defined by InvalidPathChars.

ArgumentNullException

archiveFileName is null.

PathTooLongException

archiveFileName exceeds the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.

DirectoryNotFoundException

archiveFileName is invalid, (for example, it is on an unmapped drive).

IOException

An unspecified I/O error occurred while opening the file.

UnauthorizedAccessException

archiveFileName specified a directory.

-or-

The caller does not have the required permission.

ArgumentOutOfRangeException

mode specified an invalid value.

FileNotFoundException

The file specified in archiveFileName was not found.

NotSupportedException

archiveFileName is in an invalid format.

InvalidDataException

The specified file could not be interpreted as a zip file.

-or-

mode is Update and an entry is missing from the archive or is corrupt and cannot be read.

-or-

mode is Update and an entry is too large to fit into memory.

OperationCanceledException

An asynchronous operation is cancelled.

Remarks

For archiveFileName:

The path is permitted to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory.

For mode:

If Read is specified, the file is opened with System.IO.FileMode.Open, and will throw a FileNotFoundException if the file does not exist.

If Create is specified, the file is opened with System.IO.FileMode.CreateNew, and will throw a System.IO.IOException if the file already exists.

If Update is specified, the file is opened with System.IO.FileMode.OpenOrCreate.

If the file exists and is a zip file, its entries will become accessible and can be modified, and new entries can be created.

If the file exists and is not a zip file, a InvalidDataException is thrown.

If the file exists and is empty or does not exist, a new zip file will be created.

Creating a zip file with the Create mode is more efficient when creating a new zip file.

Specifying a value other than null for entryNameEncoding is discouraged. However, this might be necessary for interoperability with zip archive tools and libraries that do not correctly support UTF-8 encoding for entry names or comments.

This value is used as follows:

  • Reading (opening) ZIP archive files:
    • If entryNameEncoding is not specified (== null):
      • For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is not set, use the current system default code page (Encoding.Default) to decode the entry name and comment.
      • For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is set, use UTF-8 (Encoding.UTF8) to decode the entry name and comment.
    • If entryNameEncoding is specified (!= null):
      • For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is not set, use the specified entryNameEncoding to decode the entry name and comment.
      • For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is set, use UTF-8 (Encoding.UTF8) to decode the entry name and comment.
  • Writing (saving) ZIP archive files:
    • If entryNameEncoding is not specified (== null):
      • For entry names and comments that contain characters outside the ASCII range, the language encoding flag (EFS) will be set in the general purpose bit flag of the local file header, and UTF-8 (Encoding.UTF8) will be used to encode the entry name and comment into bytes.
      • For entry names and comments that don't contain characters outside the ASCII range, the language encoding flag (EFS) will not be set in the general purpose bit flag of the local file header, and the current system default code page (Encoding.Default) will be used to encode the entry names and comments into bytes.
    • If entryNameEncoding is specified (!= null):
      • The specified entryNameEncoding will always be used to encode the entry names and comments into bytes.
      • The language encoding flag (EFS) in the general purpose bit flag of the local file header will be set if and only if the specified entryNameEncoding is a UTF-8 encoding.

    • Unicode encodings other than UTF-8 can't be used for the entryNameEncoding, otherwise an ArgumentException is thrown.

    Applies to