Edit

Share via

ZipArchive.CreateAsync Method

Definition

Namespace:
System.IO.Compression
Assemblies:
netstandard.dll, System.IO.Compression.dll
Source:
ZipArchive.cs

Asynchronously initializes and returns a new instance of ZipArchive on the given stream in the specified mode, specifying whether to leave the stream open, with an optional encoding and an optional cancellation token.

public static System.Threading.Tasks.Task<System.IO.Compression.ZipArchive> CreateAsync(System.IO.Stream stream, System.IO.Compression.ZipArchiveMode mode, bool leaveOpen, System.Text.Encoding? entryNameEncoding, System.Threading.CancellationToken cancellationToken = default);
static member CreateAsync : System.IO.Stream * System.IO.Compression.ZipArchiveMode * bool * System.Text.Encoding * System.Threading.CancellationToken -> System.Threading.Tasks.Task<System.IO.Compression.ZipArchive>
Public Shared Function CreateAsync (stream As Stream, mode As ZipArchiveMode, leaveOpen As Boolean, entryNameEncoding As Encoding, Optional cancellationToken As CancellationToken = Nothing) As Task(Of ZipArchive)

Parameters

stream
Stream

The input or output stream.

mode
ZipArchiveMode

One of the enumeration values that specifies whether the stream supports reading, writing, and seeking.

leaveOpen
Boolean

true to leave the stream open upon disposing the ZipArchive, otherwise false.

entryNameEncoding
Encoding

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

cancellationToken
CancellationToken

The optional cancellation token to monitor.

Returns

Task<ZipArchive>

Exceptions

ArgumentException

The stream is already closed.

-or-

mode is incompatible with the capabilities of the stream.

ArgumentNullException

The stream is null.

ArgumentOutOfRangeException

mode specified an invalid value.

InvalidDataException

The contents of the stream 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.

ArgumentException

A Unicode encoding other than UTF-8 was specified for entryNameEncoding.

Remarks

Specifying a value for entryNameEncoding other than null is discouraged. However, this might be necessary for interoperability with ZIP archive tools and libraries that don't correctly support UTF-8 encoding for entry names.

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.

    • Applies to