diff --git a/includes/remarks/System.IO.Compression/ZipFile/Open.md b/includes/remarks/System.IO.Compression/ZipFile/Open.md new file mode 100644 index 00000000000..460d04a3151 --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipFile/Open.md @@ -0,0 +1,25 @@ +When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. Setting the `mode` parameter to is equivalent to calling the method. + +When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. + +When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. + +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/ZipFile/ZipFile.md b/includes/remarks/System.IO.Compression/ZipFile/ZipFile.md new file mode 100644 index 00000000000..8a9301d412d --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipFile/ZipFile.md @@ -0,0 +1,34 @@ +> [!IMPORTANT] +> To use the class, you must add a reference to the `System.IO.Compression.FileSystem` assembly in your project; otherwise, you'll get the following error message when trying to compile : **The name 'ZipFile' does not exist in the current context**. For more information on how to add a reference to your project in Visual Studio, see [How to: Add or Remove References By Using the Reference Manager](/visualstudio/ide/how-to-add-or-remove-references-by-using-the-reference-manager). + +The methods for manipulating zip archives and their files 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 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|| + +You cannot use the or classes in Windows 8.x Store apps. In Windows 8.x Store apps, you should use the following classes to work with compressed files. + +- + +- + +- + +- + +## Examples + +This example shows how to create and extract a zip archive by using the class. It compresses the contents of a folder into a zip archive, and then extracts that content to a new folder. + +> [!TIP] +> To use the class, you must reference the `System.IO.Compression.FileSystem` assembly in your project. + +[!code-csharp[System.IO.Compression.ZipFile#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.zipfile/cs/program1.cs#1)] +[!code-vb[System.IO.Compression.ZipFile#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.zipfile/vb/program1.vb#1)] diff --git a/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md b/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md new file mode 100644 index 00000000000..081052627bb --- /dev/null +++ b/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md @@ -0,0 +1,32 @@ +The class contains only static methods that extend the and classes. You do not create an instance of the class; instead, you use these methods from instances of or . + +To use the extension methods, you must reference the `System.IO.Compression.FileSystem` assembly in your project. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8.x Store apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in Windows 8.x Store apps. In Windows 8.x Store apps, you work with compressed files by using the methods in , , , and . + +The class contains four methods that extend : + +- + +- + +- + +- + +The class contains two methods that extend : + +- + +- + +## Examples + +The following example shows how to create a new entry in a zip archive from an existing file, and extract the contents of the archive to a directory. + +[!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)] + +The following example shows how to iterate through the contents of a zip archive and extract files that have a .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)] + \ No newline at end of file diff --git a/xml/System.IO.Compression/ZipFile.xml b/xml/System.IO.Compression/ZipFile.xml index d6c09744d39..f0a162daf6a 100644 --- a/xml/System.IO.Compression/ZipFile.xml +++ b/xml/System.IO.Compression/ZipFile.xml @@ -34,47 +34,11 @@ Provides static methods for creating, extracting, and opening zip archives. - [!IMPORTANT] -> To use the class, you must add a reference to the `System.IO.Compression.FileSystem` assembly in your project; otherwise, you'll get the following error message when trying to compile : **The name 'ZipFile' does not exist in the current context**. For more information on how to add a reference to your project in Visual Studio, see [How to: Add or Remove References By Using the Reference Manager](/visualstudio/ide/how-to-add-or-remove-references-by-using-the-reference-manager). - - The methods for manipulating zip archives and their files 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 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|| - - You cannot use the or classes in Windows 8.x Store apps. In Windows 8.x Store apps, you should use the following classes to work with compressed files. - -- - -- - -- - -- - - - -## Examples - This example shows how to create and extract a zip archive by using the class. It compresses the contents of a folder into a zip archive, and then extracts that content to a new folder. - -> [!TIP] -> To use the class, you must reference the `System.IO.Compression.FileSystem` assembly in your project. - - [!code-csharp[System.IO.Compression.ZipFile#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.zipfile/cs/program1.cs#1)] - [!code-vb[System.IO.Compression.ZipFile#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.zipfile/vb/program1.vb#1)] - - ]]> + How to: Add or Remove References By Using the Reference Manager @@ -136,9 +100,7 @@ If the archive already exists, an exception is thrown. If an entry with the specified name already exists in the archive, a second entry is created with an identical name. If a file in the directory cannot be added to the archive, the archive is left incomplete and invalid, and the method throws an exception. - - - + ## Examples This example shows how to create and extract a zip archive by using the class. It compresses the contents of a folder into a zip archive, and then extracts that content to a new folder. To use the class, you must reference the `System.IO.Compression.FileSystem` assembly in your project. @@ -230,9 +192,7 @@ An I/O error occurred while opening a file to be archived. If the archive already exists, an exception is thrown. If an entry with the specified name already exists in the archive, a second entry is created with an identical name. If a file in the directory cannot be added to the archive, the archive is left incomplete and invalid, and the method throws an exception. - - - + ## Examples This example shows how to create and extract a zip archive by using the class. It compresses the contents of a folder into a zip archive, and then extracts that content to a new folder. When compressing the archive, the base directory is included and the compression level is set to emphasize the speed of the operation over efficiency. To use the class, you must reference the `System.IO.Compression.FileSystem` assembly in your project. @@ -426,9 +386,7 @@ An I/O error occurred while opening a file to be archived. ## Remarks This method creates the specified directory and all subdirectories. The destination directory cannot already exist. Exceptions related to validating the paths in the `destinationDirectoryName` or `sourceArchiveFileName` parameters are thrown before extraction. Otherwise, if an error occurs during extraction, the archive remains partially extracted. Each extracted file has the same relative path to the directory specified by `destinationDirectoryName` as its source entry has to the root of the archive. - - - + ## Examples This example shows how to create and extract a zip archive by using the class. It compresses the contents of a folder into a zip archive and extracts that content to a new folder. To use the class, you must reference the `System.IO.Compression.FileSystem` assembly in your project. @@ -822,9 +780,7 @@ An archive entry has been compressed using a compression method that is not supp When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. - - - + ## Examples The following example shows how to open a zip archive in the update mode and add an entry to the archive. @@ -917,36 +873,11 @@ An unspecified I/O error occurred while opening the file. Opens a zip archive at the specified path, in the specified mode, and by using the specified character encoding for entry names. The opened zip archive. - , the archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. Setting the `mode` parameter to is equivalent to calling the method. - - When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. - - When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. - - 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. - - ]]> + is , contains only white space, or contains at least one invalid character. diff --git a/xml/System.IO.Compression/ZipFileExtensions.xml b/xml/System.IO.Compression/ZipFileExtensions.xml index f4beae63a46..a05208fc84b 100644 --- a/xml/System.IO.Compression/ZipFileExtensions.xml +++ b/xml/System.IO.Compression/ZipFileExtensions.xml @@ -40,43 +40,11 @@ Provides extension methods for the and classes. - class contains only static methods that extend the and classes. You do not create an instance of the class; instead, you use these methods from instances of or . - - To use the extension methods, you must reference the `System.IO.Compression.FileSystem` assembly in your project. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8.x Store apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in Windows 8.x Store apps. In Windows 8.x Store apps, you work with compressed files by using the methods in , , , and . - - The class contains four methods that extend : - -- - -- - -- + +[!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md)] - The class contains two methods that extend : - -- - -- - - - -## Examples - The following example shows how to create a new entry in a zip archive from an existing file, and extract the contents of the archive to a directory. - - [!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)] - - The following example shows how to iterate through the contents of a zip archive and extract files that have a .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)] - - ]]> + ]]>