From bfcfba02dcef9e7d5ad972c9add6d350b3064240 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 18:12:06 -0800 Subject: [PATCH] Move remarks Compression --- .../CompressionLevel/CompressionLevel.md | 25 +++ .../.ctor_Stream_CompressionLevel_Boolean.md | 10 ++ .../.ctor_Stream_CompressionMode.md | 15 ++ .../.ctor_Stream_CompressionMode_Boolean.md | 14 ++ ...d_Byte_Int32_Int32_AsyncCallback_Object.md | 12 ++ ...e_Byte_Int32_Int32_AsyncCallback_Object.md | 11 ++ .../DeflateStream/DeflateStream.md | 15 ++ ...d_Byte_Int32_Int32_AsyncCallback_Object.md | 18 +++ .../GZipStream/GZipStream.md | 14 ++ ..._Stream_ZipArchiveMode_Boolean_Encoding.md | 21 +++ .../ZipArchive/ZipArchive.md | 32 ++++ .../ZipArchiveEntry/FullName.md | 11 ++ .../ZipArchiveEntry/LastWriteTime.md | 10 ++ .../ZipArchiveEntry/Name.md | 8 + .../ZipArchiveEntry/ZipArchiveEntry.md | 28 ++++ .../ZipArchiveMode/ZipArchiveMode.md | 20 +++ .../CompressionLevel.xml | 35 +---- xml/System.IO.Compression/DeflateStream.xml | 148 +++++------------- xml/System.IO.Compression/GZipStream.xml | 78 ++------- xml/System.IO.Compression/ZipArchive.xml | 92 ++--------- xml/System.IO.Compression/ZipArchiveEntry.xml | 111 +++---------- xml/System.IO.Compression/ZipArchiveMode.xml | 31 +--- 22 files changed, 365 insertions(+), 394 deletions(-) create mode 100644 includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md create mode 100644 includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel_Boolean.md create mode 100644 includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode.md create mode 100644 includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode_Boolean.md create mode 100644 includes/remarks/System.IO.Compression/DeflateStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md create mode 100644 includes/remarks/System.IO.Compression/DeflateStream/BeginWrite_Byte_Int32_Int32_AsyncCallback_Object.md create mode 100644 includes/remarks/System.IO.Compression/DeflateStream/DeflateStream.md create mode 100644 includes/remarks/System.IO.Compression/GZipStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md create mode 100644 includes/remarks/System.IO.Compression/GZipStream/GZipStream.md create mode 100644 includes/remarks/System.IO.Compression/ZipArchive/.ctor_Stream_ZipArchiveMode_Boolean_Encoding.md create mode 100644 includes/remarks/System.IO.Compression/ZipArchive/ZipArchive.md create mode 100644 includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md create mode 100644 includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md create mode 100644 includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md create mode 100644 includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md create mode 100644 includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md diff --git a/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md b/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md new file mode 100644 index 00000000000..fc3e674107f --- /dev/null +++ b/includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md @@ -0,0 +1,25 @@ +Compression operations usually involve a tradeoff between the speed and the effectiveness of compression. You use the enumeration to indicate which factor is more important in your development scenario: the time to complete the compression operation or the size of the compressed file. These values do not correspond to specific compression levels; the object that implements compression determines how to handle them. + +The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: + +- + +- + +- + +- + +- + +- + +- + +## Examples + +The following example shows how to set the compression level when creating a zip archive by using the class. + +[!code-csharp[System.IO.Compression.ZipFile#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.zipfile/cs/program3.cs#3)] +[!code-vb[System.IO.Compression.ZipFile#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.zipfile/vb/program3.vb#3)] + diff --git a/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel_Boolean.md b/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel_Boolean.md new file mode 100644 index 00000000000..a966ae991c1 --- /dev/null +++ b/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel_Boolean.md @@ -0,0 +1,10 @@ +You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class, and whether to leave the stream object open after disposing the object. + +This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + +## Examples + +The following example shows how to set the compression level when creating a object and how to leave the stream open. + +[!code-csharp[System.IO.Compression.DeflateStream#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.deflatestream/cs/program2.cs#2)] +[!code-vb[System.IO.Compression.DeflateStream#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.deflatestream/vb/program2.vb#2)] diff --git a/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode.md b/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode.md new file mode 100644 index 00000000000..cd7de91f078 --- /dev/null +++ b/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode.md @@ -0,0 +1,15 @@ +By default, owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. + +If an instance of the class is created with the `mode` parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. + +Using the class to compress a file larger than 4 GB raises an exception. + +By default, the compression level is set to when the compression mode is . + +## Examples + +The following example shows how to use the class to compress and decompress a file. + +[!code-csharp[IO.Compression.Deflate1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.Deflate1/CS/deflatetest.cs#1)] +[!code-vb[IO.Compression.Deflate1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.Deflate1/VB/deflatetest.vb#1)] + diff --git a/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode_Boolean.md b/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode_Boolean.md new file mode 100644 index 00000000000..5d29cea3e83 --- /dev/null +++ b/includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode_Boolean.md @@ -0,0 +1,14 @@ +By default, owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. + +If an instance of the class is created with the `mode` parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. + +Using the class to compress a file larger than 4 GB raises an exception. + +By default, the compression level is set to when the compression mode is . + +## Examples + +The following code example shows how to use the class to compress and decompress a file. + +[!code-csharp[IO.Compression.Deflate1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.Deflate1/CS/deflatetest.cs#1)] +[!code-vb[IO.Compression.Deflate1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.Deflate1/VB/deflatetest.vb#1)] diff --git a/includes/remarks/System.IO.Compression/DeflateStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md b/includes/remarks/System.IO.Compression/DeflateStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md new file mode 100644 index 00000000000..0c93fadec63 --- /dev/null +++ b/includes/remarks/System.IO.Compression/DeflateStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md @@ -0,0 +1,12 @@ +Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + +Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . + +The current position in the stream is updated when the asynchronous read or write operation is issued, not when the I/O operation completes. + +Multiple simultaneous asynchronous requests render the request completion order uncertain. + +Use the property to determine whether the current object supports reading. + +If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . + \ No newline at end of file diff --git a/includes/remarks/System.IO.Compression/DeflateStream/BeginWrite_Byte_Int32_Int32_AsyncCallback_Object.md b/includes/remarks/System.IO.Compression/DeflateStream/BeginWrite_Byte_Int32_Int32_AsyncCallback_Object.md new file mode 100644 index 00000000000..677f67286ea --- /dev/null +++ b/includes/remarks/System.IO.Compression/DeflateStream/BeginWrite_Byte_Int32_Int32_AsyncCallback_Object.md @@ -0,0 +1,11 @@ +Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + +Pass the object returned by the current method to to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called or in a callback passed to . If an error occurs during an asynchronous write operation, an exception will not be thrown until is called with the returned by this method. + +If a stream is writable, writing at the end of the stream expands the stream. + +The current position in the stream is updated when you issue the asynchronous read or write operation, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. + +Use the property to determine whether the current object supports writing. + +If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . diff --git a/includes/remarks/System.IO.Compression/DeflateStream/DeflateStream.md b/includes/remarks/System.IO.Compression/DeflateStream/DeflateStream.md new file mode 100644 index 00000000000..790cc485c49 --- /dev/null +++ b/includes/remarks/System.IO.Compression/DeflateStream/DeflateStream.md @@ -0,0 +1,15 @@ + +This class represents the Deflate algorithm, which is an industry-standard algorithm for lossless file compression and decompression. Starting with the .NET Framework 4.5, the class uses the zlib library. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of the .NET Framework. + +This class does not inherently provide functionality for adding files to or extracting files from zip archives. To work with zip archives, use the and the classes. + +The class uses the same compression algorithm as the gzip data format used by the class. + +The compression functionality in and is exposed as a stream. Data is read on a byte-by-byte basis, so it is not possible to perform multiple passes to determine the best method for compressing entire files or large blocks of data. The and classes are best used on uncompressed sources of data. If the source data is already compressed, using these classes may actually increase the size of the stream. + +## Examples + +The following example shows how to use the class to compress and decompress a directory of files. + +[!code-csharp[IO.Compression.Deflate1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.Deflate1/CS/deflatetest.cs#1)] +[!code-vb[IO.Compression.Deflate1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.Deflate1/VB/deflatetest.vb#1)] diff --git a/includes/remarks/System.IO.Compression/GZipStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md b/includes/remarks/System.IO.Compression/GZipStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md new file mode 100644 index 00000000000..c7c8919dd59 --- /dev/null +++ b/includes/remarks/System.IO.Compression/GZipStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md @@ -0,0 +1,18 @@ +Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + +Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . + +The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. + +Multiple simultaneous asynchronous requests render the request completion order uncertain. + +Use the property to determine whether the current object supports reading. + +If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . + +## Examples + +The following code example shows how to use the class to compress and decompress a file. + +[!code-csharp[IO.Compression.GZip1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.GZip1/CS/gziptest.cs#1)] +[!code-vb[IO.Compression.GZip1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.GZip1/VB/gziptest.vb#1)] diff --git a/includes/remarks/System.IO.Compression/GZipStream/GZipStream.md b/includes/remarks/System.IO.Compression/GZipStream/GZipStream.md new file mode 100644 index 00000000000..fa5f811fc89 --- /dev/null +++ b/includes/remarks/System.IO.Compression/GZipStream/GZipStream.md @@ -0,0 +1,14 @@ +This class represents the gzip data format, which uses an industry-standard algorithm for lossless file compression and decompression. The format includes a cyclic redundancy check value for detecting data corruption. The gzip data format uses the same algorithm as the class, but can be extended to use other compression formats. The format can be readily implemented in a manner not covered by patents. + +Starting with the .NET Framework 4.5, the class uses the zlib library for compression. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of the .NET Framework. + +Compressed objects written to a file with an extension of .gz can be decompressed using many common compression tools; however, this class does not inherently provide functionality for adding files to or extracting files from zip archives. + +The compression functionality in and is exposed as a stream. Data is read on a byte-by-byte basis, so it is not possible to perform multiple passes to determine the best method for compressing entire files or large blocks of data. The and classes are best used on uncompressed sources of data. If the source data is already compressed, using these classes may actually increase the size of the stream. + +## Examples + +The following example shows how to use the class to compress and decompress a directory of files. + +[!code-csharp[IO.Compression.GZip1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.GZip1/CS/gziptest.cs#1)] +[!code-vb[IO.Compression.GZip1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.GZip1/VB/gziptest.vb#1)] diff --git a/includes/remarks/System.IO.Compression/ZipArchive/.ctor_Stream_ZipArchiveMode_Boolean_Encoding.md b/includes/remarks/System.IO.Compression/ZipArchive/.ctor_Stream_ZipArchiveMode_Boolean_Encoding.md new file mode 100644 index 00000000000..dc5e6529c83 --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipArchive/.ctor_Stream_ZipArchiveMode_Boolean_Encoding.md @@ -0,0 +1,21 @@ +If the `mode` parameter is set to , the stream must support reading. If the `mode` parameter is set to , the stream must support writing. If the `mode` parameter is set to , the stream must support reading, writing, and seeking. + +When you open a zip archive file for reading and `entryNameEncoding` is set to `null`, entry names are decoded according to the following rules: + +- When the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the current system default code page is used to decode the entry name. + +- When the language encoding flag is set, UTF-8 is used to decode the entry name. + +When you open a zip archive file for reading and `entryNameEncoding` is set to a value other than `null`, entry names are decoded according to the following rules: + +- When the language encoding flag is not set, the specified `entryNameEncoding` is used to decode the entry name. + +- When the language encoding flag is set, UTF-8 is used to decode the entry name. + +When you write to archive files and `entryNameEncoding` is set to `null`, entry names are encoded according to the following rules: + +- For entry names that contain characters outside the ASCII range, the language encoding flag is set, and entry names are encoded by using UTF-8. + +- For entry names that contain only ASCII characters, the language encoding flag is not set, and entry names are encoded by using the current system default code page. + +When you write to archive files and `entryNameEncoding` is set to a value other than `null`, the specified `entryNameEncoding` is used to encode the entry names into bytes. The language encoding flag (in the general-purpose bit flag of the local file header) is set only when the specified encoding is a UTF-8 encoding. diff --git a/includes/remarks/System.IO.Compression/ZipArchive/ZipArchive.md b/includes/remarks/System.IO.Compression/ZipArchive/ZipArchive.md new file mode 100644 index 00000000000..226b1565e8c --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipArchive/ZipArchive.md @@ -0,0 +1,32 @@ +The methods for manipulating zip archives and their file entries are spread across three classes: , , and . + +|To|Use| +|--------|---------| +|Create a zip archive from a directory|| +|Extract the contents of a zip archive to a directory|| +|Add new files to an existing zip archive|| +|Retrieve a file from a zip archive|| +|Retrieve all the files from a zip archive|| +|Open a stream to a single file contained in a zip archive|| +|Delete a file from a zip archive|| + +When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. + +If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access four extension methods (from the class) for the class: , , , and (available in .NET Core 2.0 and later versions). These extension methods enable you to compress and decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available for Windows 8.x Store apps. In Windows 8.x Store apps, you can compress and decompress files by using the or class, or you can use the Windows Runtime types [Compressor](https://go.microsoft.com/fwlink/p/?LinkID=246357) and [Decompressor](https://go.microsoft.com/fwlink/p/?LinkID=246358). + +## Examples + +The first example shows how to create a new entry and write to it by using a stream. + +[!code-csharp[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/cs/program1.cs#1)] +[!code-vb[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/vb/program1.vb#1)] + +The following example shows how to open a zip archive and iterate through the collection of entries. + +[!code-csharp[System.IO.Compression.ZipArchive#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program1.cs#1)] +[!code-vb[System.IO.Compression.ZipArchive#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb#1)] + +The third example shows how to use extension methods to create a new entry in a zip archive from an existing file and extract the archive contents. You must reference the `System.IO.Compression.FileSystem` assembly to execute the code. + +[!code-csharp[System.IO.Compression.ZipArchive#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program3.cs#3)] +[!code-vb[System.IO.Compression.ZipArchive#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program3.vb#3)] diff --git a/includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md b/includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md new file mode 100644 index 00000000000..2a06be2c185 --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md @@ -0,0 +1,11 @@ +The property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. + +You can specify any string as the path of an entry, including strings that specify invalid and absolute paths. Therefore, the property might contain a value that is not correctly formatted. An invalid or absolute path might result in an exception when you extract the contents of the zip archive. + +## Examples + +The following example shows how to iterate through the contents of a .zip file, and extract files that contain the .txt extension. + +[!code-csharp[System.IO.Compression.ZipArchive#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program1.cs#1)] +[!code-vb[System.IO.Compression.ZipArchive#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb#1)] + diff --git a/includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md b/includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md new file mode 100644 index 00000000000..c2b60111931 --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md @@ -0,0 +1,10 @@ +When you create a new entry from an existing file by calling the method, the property for the entry is automatically set to the last time the file was modified. When you create a new entry programmatically by calling the method, the property for the entry is automatically set to the time of execution. If you modify the entry, you must explicitly set the property if you want the value to reflect the time of the latest change. + +When you set this property, the value is converted to a timestamp format that is specific to zip archives. This format supports a resolution of two seconds. The earliest permitted value is 1980 January 1 0:00:00 (midnight). The latest permitted value is 2107 December 31 23:59:58 (one second before midnight). If the value for the last write time is not valid, the property returns a default value of 1980 January 1 0:00:00 (midnight). + +## Examples + +The following example shows how to open an entry in a zip archive, modify it, and set the property to the current time. + +[!code-csharp[System.IO.Compression.ZipArchiveEntry#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/cs/program2.cs#2)] +[!code-vb[System.IO.Compression.ZipArchiveEntry#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/vb/program2.vb#2)] diff --git a/includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md b/includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md new file mode 100644 index 00000000000..020cca38b57 --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md @@ -0,0 +1,8 @@ +The property contains the portion of the property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. + +## Examples + +The following example shows how to retrieve entries from a zip archive and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + +[!code-csharp[System.IO.Compression.ZipArchiveEntry#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/cs/program1.cs#1)] +[!code-vb[System.IO.Compression.ZipArchiveEntry#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/vb/program1.vb#1)] diff --git a/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md b/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md new file mode 100644 index 00000000000..c0f1257f606 --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md @@ -0,0 +1,28 @@ +A zip archive contains an entry for each compressed file. The class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. + +The methods for manipulating zip archives and their file entries are spread across three classes: , and . + +|To...|Use...| +|---------|----------| +|Create a zip archive from a directory|| +|Extract the contents of a zip archive to a directory|| +|Add new files to an existing zip archive|| +|Retrieve an file in a zip archive|| +|Retrieve all of the files in a zip archive|| +|To open a stream to an individual file contained in a zip archive|| +|Delete a file from a zip archive|| + +If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types [Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor](https://go.microsoft.com/fwlink/?LinkId=246358) to compress and decompress files. + +## Examples + +The first example shows how to create a new entry in a zip archive and write to it. + +[!code-csharp[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/cs/program1.cs#1)] +[!code-vb[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/vb/program1.vb#1)] + +The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. + +[!code-csharp[System.IO.Compression.ZipArchive#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program1.cs#1)] +[!code-vb[System.IO.Compression.ZipArchive#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb#1)] + diff --git a/includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md b/includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md new file mode 100644 index 00000000000..f0a781db59f --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md @@ -0,0 +1,20 @@ +When you set the mode to Read, the underlying file or stream must support reading, but does not have to support seeking. If the underlying file or stream supports seeking, the files are read from the archive as they are requested. If the underlying file or stream does not support seeking, the entire archive is held in memory. + +When you set the mode to Create, the underlying file or stream must support writing, but does not have to support seeking. Each entry in the archive can be opened only once for writing. If you create a single entry, the data is written to the underlying stream or file as soon as it is available. If you create multiple entries, such as by calling the method, the data is written to the underlying stream or file after all the entries are created. + +When you set the mode to Update, the underlying file or stream must support reading, writing, and seeking. The content of the entire archive is held in memory, and no data is written to the underlying file or stream until the archive is disposed. + +The following methods include a parameter named `mode` that lets you specify the archive mode: + +- + +- + +- + +## Examples + +The following example shows how to specify a `ZipArchiveMode` value when creating a object. + +[!code-csharp[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/cs/program1.cs#1)] +[!code-vb[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/vb/program1.vb#1)] diff --git a/xml/System.IO.Compression/CompressionLevel.xml b/xml/System.IO.Compression/CompressionLevel.xml index bed39d48452..bf35b44023d 100644 --- a/xml/System.IO.Compression/CompressionLevel.xml +++ b/xml/System.IO.Compression/CompressionLevel.xml @@ -37,36 +37,11 @@ Specifies values that indicate whether a compression operation emphasizes speed or compression size. - enumeration to indicate which factor is more important in your development scenario: the time to complete the compression operation or the size of the compressed file. These values do not correspond to specific compression levels; the object that implements compression determines how to handle them. - - The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - The following example shows how to set the compression level when creating a zip archive by using the class. - - [!code-csharp[System.IO.Compression.ZipFile#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.zipfile/cs/program3.cs#3)] - [!code-vb[System.IO.Compression.ZipFile#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.zipfile/vb/program3.vb#3)] - - ]]> + diff --git a/xml/System.IO.Compression/DeflateStream.xml b/xml/System.IO.Compression/DeflateStream.xml index 736d6d7be7c..253025cb3a2 100644 --- a/xml/System.IO.Compression/DeflateStream.xml +++ b/xml/System.IO.Compression/DeflateStream.xml @@ -39,26 +39,11 @@ Provides methods and properties for compressing and decompressing streams by using the Deflate algorithm. - class uses the zlib library. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of the .NET Framework. - - This class does not inherently provide functionality for adding files to or extracting files from zip archives. To work with zip archives, use the and the classes. - - The class uses the same compression algorithm as the gzip data format used by the class. - - The compression functionality in and is exposed as a stream. Data is read on a byte-by-byte basis, so it is not possible to perform multiple passes to determine the best method for compressing entire files or large blocks of data. The and classes are best used on uncompressed sources of data. If the source data is already compressed, using these classes may actually increase the size of the stream. - - - -## Examples - The following example shows how to use the class to compress and decompress a directory of files. - - [!code-csharp[IO.Compression.Deflate1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.Deflate1/CS/deflatetest.cs#1)] - [!code-vb[IO.Compression.Deflate1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.Deflate1/VB/deflatetest.vb#1)] - - ]]> + @@ -73,7 +58,8 @@ class to compress a file larger than 4 GB will cause an exception. ]]> @@ -119,12 +105,11 @@ class. This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. - - - + ## Examples The following example shows how to set the compression level when creating a object. @@ -181,26 +166,11 @@ One of the enumeration values that indicates whether to compress or decompress the stream. Initializes a new instance of the class by using the specified stream and compression mode. - owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. - - If an instance of the class is created with the `mode` parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. - - Using the class to compress a file larger than 4 GB raises an exception. - - By default, the compression level is set to when the compression mode is . - - - -## Examples - The following example shows how to use the class to compress and decompress a file. - - [!code-csharp[IO.Compression.Deflate1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.Deflate1/CS/deflatetest.cs#1)] - [!code-vb[IO.Compression.Deflate1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.Deflate1/VB/deflatetest.vb#1)] - - ]]> + is . @@ -255,22 +225,11 @@ to leave the stream object open after disposing the object; otherwise, . Initializes a new instance of the class by using the specified stream and compression level, and optionally leaves the stream open. - class, and whether to leave the stream object open after disposing the object. - - This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. - - - -## Examples - The following example shows how to set the compression level when creating a object and how to leave the stream open. - - [!code-csharp[System.IO.Compression.DeflateStream#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.deflatestream/cs/program2.cs#2)] - [!code-vb[System.IO.Compression.DeflateStream#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.deflatestream/vb/program2.vb#2)] - - ]]> + is . @@ -317,26 +276,11 @@ to leave the stream open after disposing the object; otherwise, . Initializes a new instance of the class by using the specified stream and compression mode, and optionally leaves the stream open. - owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. - - If an instance of the class is created with the `mode` parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. - - Using the class to compress a file larger than 4 GB raises an exception. - - By default, the compression level is set to when the compression mode is . - - - -## Examples - The following code example shows how to use the class to compress and decompress a file. - - [!code-csharp[IO.Compression.Deflate1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.Deflate1/CS/deflatetest.cs#1)] - [!code-vb[IO.Compression.Deflate1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.Deflate1/VB/deflatetest.vb#1)] - - ]]> + is . @@ -459,21 +403,10 @@ An object that represents the asynchronous read operation, which could still be pending. method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). - - Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . - - The current position in the stream is updated when the asynchronous read or write operation is issued, not when the I/O operation completes. - - Multiple simultaneous asynchronous requests render the request completion order uncertain. - - Use the property to determine whether the current object supports reading. - - If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . - - ]]> + +[!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/DeflateStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md)] + + ]]> The method tried to read asynchronously past the end of the stream, or a disk error occurred. One or more of the arguments is invalid. @@ -539,22 +472,11 @@ Begins an asynchronous write operation. (Consider using the method instead.) An object that represents the asynchronous write operation, which could still be pending. - method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). - - Pass the object returned by the current method to to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called or in a callback passed to . If an error occurs during an asynchronous write operation, an exception will not be thrown until is called with the returned by this method. - - If a stream is writable, writing at the end of the stream expands the stream. - - The current position in the stream is updated when you issue the asynchronous read or write operation, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. - - Use the property to determine whether the current object supports writing. - - If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . - - ]]> + The method tried to write asynchronously past the end of the stream, or a disk error occurred. One or more of the arguments is invalid. @@ -812,6 +734,7 @@ Copying begins at the current position in the current Deflate stream. method and the method. invokes the protected method with the `disposing` parameter set to `true`. invokes with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. @@ -916,6 +839,7 @@ Calling `DisposeAsync` allows the resources used by the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . @@ -982,6 +906,7 @@ The stream is . method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). must be called only once for every call to the method. @@ -1040,6 +965,7 @@ The end write call is invalid. . ]]> diff --git a/xml/System.IO.Compression/GZipStream.xml b/xml/System.IO.Compression/GZipStream.xml index f7691cc0dda..eb5bd203da5 100644 --- a/xml/System.IO.Compression/GZipStream.xml +++ b/xml/System.IO.Compression/GZipStream.xml @@ -39,26 +39,11 @@ Provides methods and properties used to compress and decompress streams by using the GZip data format specification. - class, but can be extended to use other compression formats. The format can be readily implemented in a manner not covered by patents. - - Starting with the .NET Framework 4.5, the class uses the zlib library for compression. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of the .NET Framework. - - Compressed objects written to a file with an extension of .gz can be decompressed using many common compression tools; however, this class does not inherently provide functionality for adding files to or extracting files from zip archives. - - The compression functionality in and is exposed as a stream. Data is read on a byte-by-byte basis, so it is not possible to perform multiple passes to determine the best method for compressing entire files or large blocks of data. The and classes are best used on uncompressed sources of data. If the source data is already compressed, using these classes may actually increase the size of the stream. - - - -## Examples - The following example shows how to use the class to compress and decompress a directory of files. - - [!code-csharp[IO.Compression.GZip1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.GZip1/CS/gziptest.cs#1)] - [!code-vb[IO.Compression.GZip1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.GZip1/VB/gziptest.vb#1)] - - ]]> + When you inherit from , you must override the following members: , , and . @@ -118,9 +103,7 @@ You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class. This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. - - - + ## Examples The following example shows how to set the compression level when creating a object. @@ -185,9 +168,7 @@ If an instance of the class is created with the `mode` parameter equal to `Compress` and no further action occurs, the stream will appear as a valid, empty compressed file. By default, the compression level is set to when the compression mode is . - - - + ## Examples The following example initializes a new instance of the class with `mode` set to . This example is part of a larger example provided for the class. @@ -255,9 +236,7 @@ You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class, and whether to leave the stream object open after disposing the object. This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. - - - + ## Examples The following example shows how to set the compression level when creating a object and how to leave the stream open. @@ -432,29 +411,10 @@ An object that represents the asynchronous read operation, which could still be pending. method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). - - Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . - - The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. - - Multiple simultaneous asynchronous requests render the request completion order uncertain. - - Use the property to determine whether the current object supports reading. - - If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . - - - -## Examples - The following code example shows how to use the class to compress and decompress a file. - - [!code-csharp[IO.Compression.GZip1#1](~/samples/snippets/csharp/VS_Snippets_CLR/IO.Compression.GZip1/CS/gziptest.cs#1)] - [!code-vb[IO.Compression.GZip1#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/IO.Compression.GZip1/VB/gziptest.vb#1)] - - ]]> + +[!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/GZipStream/BeginRead_Byte_Int32_Int32_AsyncCallback_Object.md)] + + ]]> The method tried to read asynchronously past the end of the stream, or a disk error occurred. One or more of the arguments is invalid. @@ -905,9 +865,7 @@ Calling `DisposeAsync` allows the resources used by the and . This method blocks until the I/O operation has completed. - - - + ## Examples The following code example shows how to use the class to compress and decompress a file. @@ -1238,10 +1196,8 @@ This method read a maximum of `buffer.Length` bytes from the current stream and is thrown as one of the last operations. A cyclic redundancy check (CRC) is performed as one of the last operations of this method. - - - + If data is found in an invalid format, an is thrown as one of the last operations. A cyclic redundancy check (CRC) is performed as one of the last operations of this method. + ## Examples The following example shows how to compress and decompress bytes by using the and methods. @@ -1581,9 +1537,7 @@ If the write operation is successful, the position within the GZip stream advanc ## Remarks The write operation might not occur immediately but is buffered until the buffer size is reached or until the or method is called. - - - + ## Examples The following example shows how to compress and decompress bytes by using the and methods. diff --git a/xml/System.IO.Compression/ZipArchive.xml b/xml/System.IO.Compression/ZipArchive.xml index db35ee15069..0567d17bccd 100644 --- a/xml/System.IO.Compression/ZipArchive.xml +++ b/xml/System.IO.Compression/ZipArchive.xml @@ -34,44 +34,11 @@ Represents a package of compressed files in the zip archive format. - , , and . - -|To|Use| -|--------|---------| -|Create a zip archive from a directory|| -|Extract the contents of a zip archive to a directory|| -|Add new files to an existing zip archive|| -|Retrieve a file from a zip archive|| -|Retrieve all the files from a zip archive|| -|Open a stream to a single file contained in a zip archive|| -|Delete a file from a zip archive|| - - When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. - - If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access four extension methods (from the class) for the class: , , , and (available in .NET Core 2.0 and later versions). These extension methods enable you to compress and decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available for Windows 8.x Store apps. In Windows 8.x Store apps, you can compress and decompress files by using the or class, or you can use the Windows Runtime types [Compressor](https://go.microsoft.com/fwlink/p/?LinkID=246357) and [Decompressor](https://go.microsoft.com/fwlink/p/?LinkID=246358). - - - -## Examples - The first example shows how to create a new entry and write to it by using a stream. - - [!code-csharp[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/cs/program1.cs#1)] - [!code-vb[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/vb/program1.vb#1)] - - The following example shows how to open a zip archive and iterate through the collection of entries. - - [!code-csharp[System.IO.Compression.ZipArchive#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program1.cs#1)] - [!code-vb[System.IO.Compression.ZipArchive#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb#1)] - - The third example shows how to use extension methods to create a new entry in a zip archive from an existing file and extract the archive contents. You must reference the `System.IO.Compression.FileSystem` assembly to execute the code. - - [!code-csharp[System.IO.Compression.ZipArchive#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program3.cs#3)] - [!code-vb[System.IO.Compression.ZipArchive#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program3.vb#3)] - - ]]> + @@ -275,32 +242,11 @@ The encoding to use when reading or writing entry names in this archive. Specify a value for this parameter only when an encoding is required for interoperability with zip archive tools and libraries that do not support UTF-8 encoding for entry names. Initializes a new instance of the class on the specified stream for the specified mode, uses the specified encoding for entry names, and optionally leaves the stream open. - , the stream must support reading. If the `mode` parameter is set to , the stream must support writing. If the `mode` parameter is set to , the stream must support reading, writing, and seeking. - - When you open a zip archive file for reading and `entryNameEncoding` is set to `null`, entry names are decoded according to the following rules: - -- When the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the current system default code page is used to decode the entry name. - -- When the language encoding flag is set, UTF-8 is used to decode the entry name. - - When you open a zip archive file for reading and `entryNameEncoding` is set to a value other than `null`, entry names are decoded according to the following rules: - -- When the language encoding flag is not set, the specified `entryNameEncoding` is used to decode the entry name. - -- When the language encoding flag is set, UTF-8 is used to decode the entry name. - - When you write to archive files and `entryNameEncoding` is set to `null`, entry names are encoded according to the following rules: - -- For entry names that contain characters outside the ASCII range, the language encoding flag is set, and entry names are encoded by using UTF-8. - -- For entry names that contain only ASCII characters, the language encoding flag is not set, and entry names are encoded by using the current system default code page. - - When you write to archive files and `entryNameEncoding` is set to a value other than `null`, the specified `entryNameEncoding` is used to encode the entry names into bytes. The language encoding flag (in the general-purpose bit flag of the local file header) is set only when the specified encoding is a UTF-8 encoding. - - ]]> + The stream is already closed, or the capabilities of the stream do not match the mode. @@ -374,9 +320,7 @@ An encoding other than UTF-8 is specified for the property for the new entry is set to the current time. Set the `compressionLevel` parameter to if you want the file to be compressed as much as possible. Set the `compressionLevel` parameter to only if you are concerned that the compression operation will not complete quickly enough for your scenario. - - - + ## Examples The following example shows how to create an entry with the optimal compression level. It also writes to the new entry by using a stream. @@ -598,10 +540,8 @@ An encoding other than UTF-8 is specified for the property to retrieve the entire collection of entries. Use the method to retrieve a single entry by name. - - - + Use the property to retrieve the entire collection of entries. Use the method to retrieve a single entry by name. + ## Examples The following example shows how to open a zip archive and iterate through the collection of entries. @@ -654,9 +594,7 @@ An encoding other than UTF-8 is specified for the class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. - - The methods for manipulating zip archives and their file entries are spread across three classes: , and . - -|To...|Use...| -|---------|----------| -|Create a zip archive from a directory|| -|Extract the contents of a zip archive to a directory|| -|Add new files to an existing zip archive|| -|Retrieve an file in a zip archive|| -|Retrieve all of the files in a zip archive|| -|To open a stream to an individual file contained in a zip archive|| -|Delete a file from a zip archive|| - - If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types [Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor](https://go.microsoft.com/fwlink/?LinkId=246358) to compress and decompress files. - - - -## Examples - The first example shows how to create a new entry in a zip archive and write to it. - - [!code-csharp[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/cs/program1.cs#1)] - [!code-vb[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/vb/program1.vb#1)] - - The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. - - [!code-csharp[System.IO.Compression.ZipArchive#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program1.cs#1)] - [!code-vb[System.IO.Compression.ZipArchive#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb#1)] - - ]]> + @@ -132,9 +104,7 @@ ## Remarks This property cannot be retrieved when the mode is set to , or the mode is set to and the entry has been opened. - - - + ## Examples The following example shows how to retrieve entries in a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. @@ -279,22 +249,11 @@ Gets the relative path of the entry in the zip archive. The relative path of the entry in the zip archive. - property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. - - You can specify any string as the path of an entry, including strings that specify invalid and absolute paths. Therefore, the property might contain a value that is not correctly formatted. An invalid or absolute path might result in an exception when you extract the contents of the zip archive. - - - -## Examples - The following example shows how to iterate through the contents of a .zip file, and extract files that contain the .txt extension. - - [!code-csharp[System.IO.Compression.ZipArchive#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program1.cs#1)] - [!code-vb[System.IO.Compression.ZipArchive#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb#1)] - - ]]> + @@ -328,22 +287,11 @@ Gets or sets the last time the entry in the zip archive was changed. The last time the entry in the zip archive was changed. - method, the property for the entry is automatically set to the last time the file was modified. When you create a new entry programmatically by calling the method, the property for the entry is automatically set to the time of execution. If you modify the entry, you must explicitly set the property if you want the value to reflect the time of the latest change. - - When you set this property, the value is converted to a timestamp format that is specific to zip archives. This format supports a resolution of two seconds. The earliest permitted value is 1980 January 1 0:00:00 (midnight). The latest permitted value is 2107 December 31 23:59:58 (one second before midnight). If the value for the last write time is not valid, the property returns a default value of 1980 January 1 0:00:00 (midnight). - - - -## Examples - The following example shows how to open an entry in a zip archive, modify it, and set the property to the current time. - - [!code-csharp[System.IO.Compression.ZipArchiveEntry#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/cs/program2.cs#2)] - [!code-vb[System.IO.Compression.ZipArchiveEntry#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/vb/program2.vb#2)] - - ]]> + The attempt to set this property failed, because the zip archive for the entry is in mode. The archive mode is set to . @@ -388,9 +336,7 @@ ## Remarks This property cannot be retrieved when the mode is set to , or the mode is set to and the entry has been opened. - - - + ## Examples The following example shows how to retrieve entries from a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. @@ -432,20 +378,11 @@ Gets the file name of the entry in the zip archive. The file name of the entry in the zip archive. - property contains the portion of the property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. - - - -## Examples - The following example shows how to retrieve entries from a zip archive and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. - - [!code-csharp[System.IO.Compression.ZipArchiveEntry#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/cs/program1.cs#1)] - [!code-vb[System.IO.Compression.ZipArchiveEntry#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchiveentry/vb/program1.vb#1)] - - ]]> + @@ -484,9 +421,7 @@ ## Remarks You use this method to access the stream for an entry in a zip archive. After retrieving the stream, you can read from or write to the stream. When you write to the stream, the modifications you make to the entry will appear in the zip archive. - - - + ## Examples The following example shows how to create a new entry, open it with the method, and write to the stream. diff --git a/xml/System.IO.Compression/ZipArchiveMode.xml b/xml/System.IO.Compression/ZipArchiveMode.xml index db5d72dc83b..c74b9eb61e6 100644 --- a/xml/System.IO.Compression/ZipArchiveMode.xml +++ b/xml/System.IO.Compression/ZipArchiveMode.xml @@ -29,32 +29,11 @@ Specifies values for interacting with zip archive entries. - method, the data is written to the underlying stream or file after all the entries are created. - - When you set the mode to Update, the underlying file or stream must support reading, writing, and seeking. The content of the entire archive is held in memory, and no data is written to the underlying file or stream until the archive is disposed. - - The following methods include a parameter named `mode` that lets you specify the archive mode: - -- - -- - -- - - - -## Examples - The following example shows how to specify a `ZipArchiveMode` value when creating a object. - - [!code-csharp[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/cs/program1.cs#1)] - [!code-vb[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/vb/program1.vb#1)] - - ]]> +