From 043825757ebc0f2bf3e22be6d3c5f3498d0ab03a Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Mon, 22 Feb 2021 16:40:17 -0800 Subject: [PATCH 1/8] Backport System.IO.Compression.ZipFile docs --- .../System/IO/Compression/ZipFile.Create.cs | 486 ++++++++---------- .../System/IO/Compression/ZipFile.Extract.cs | 317 ++++++------ .../ZipFileExtensions.ZipArchive.Create.cs | 135 ++--- .../ZipFileExtensions.ZipArchive.Extract.cs | 120 +++-- ...pFileExtensions.ZipArchiveEntry.Extract.cs | 136 +++-- 5 files changed, 586 insertions(+), 608 deletions(-) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs index b363d123111737..12d67e49224b78 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs @@ -8,141 +8,135 @@ namespace System.IO.Compression { + /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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 public static partial class ZipFile { - /// - /// Opens a ZipArchive on the specified path for reading. The specified file is opened with FileMode.Open. - /// - /// - /// archiveFileName is a zero-length string, contains only whitespace, or contains one - /// or more invalid characters as defined by InvalidPathChars. - /// archiveFileName is null. - /// The specified 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. - /// The specified archiveFileName is invalid, (for example, it is on an unmapped drive). - /// An unspecified I/O error occurred while opening the file. - /// archiveFileName specified a directory. - /// -OR- The caller does not have the required permission. - /// The file specified in archiveFileName was not found. - /// archiveFileName is in an invalid format. - /// The specified file could not be interpreted as a Zip file. - /// - /// A string specifying the path on the filesystem to open the archive on. The path is permitted - /// to specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. + /// Opens a zip archive for reading at the specified path. + /// The path to the archive to open, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// The opened zip archive. + /// method and setting the `mode` parameter to . The archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. + /// ## Examples + /// The following example shows how to open a zip archive for reading. + /// [!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)] + /// ]]> + /// is , contains only white space, or contains at least one invalid character. + /// is . + /// In , the specified path, file name, or both exceed the system-defined maximum length. + /// is invalid or does not exist (for example, it is on an unmapped drive). + /// could not be opened. + /// -or- + /// An unspecified I/O error occurred while opening the file. + /// specifies a directory. + /// -or- + /// The caller does not have the required permission to access the file specified in . + /// The file specified in is not found. + /// contains an invalid format. + /// could not be interpreted as a zip archive. public static ZipArchive OpenRead(string archiveFileName) => Open(archiveFileName, ZipArchiveMode.Read); - /// - /// Opens a ZipArchive on the specified archiveFileName in the specified ZipArchiveMode mode. - /// - /// - /// archiveFileName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. - /// path is null. - /// The specified 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. - /// The specified archiveFileName is invalid, (for example, it is on an unmapped drive). - /// An unspecified I/O error occurred while opening the file. - /// archiveFileName specified a directory. - /// -OR- The caller does not have the required permission. - /// mode specified an invalid value. - /// The file specified in archiveFileName was not found. - /// archiveFileName is in an invalid format. - /// 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. - /// - /// A string specifying the path on the filesystem to open the archive on. - /// The path is permitted to specify relative or absolute path information. - /// Relative path information is interpreted as relative to the current working directory. - /// See the description of the ZipArchiveMode enum. - /// 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 may be modified, and new entries may be created. - /// If the file exists and is not a Zip file, a ZipArchiveException will be thrown. - /// If the file exists and is empty or does not exist, a new Zip file will be created. - /// Note that creating a Zip file with the ZipArchiveMode.Create mode is more efficient when creating a new Zip file. + /// Opens a zip archive at the specified path and in the specified mode. + /// The path to the archive to open, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// One of the enumeration values that specifies the actions which are allowed on the entries in the opened archive. + /// The opened zip archive. + /// , the archive is opened with from the enumeration 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. + /// ## Examples + /// The following example shows how to open a zip archive in the update mode and add an entry to the archive. + /// [!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)] + /// ]]> + /// is , contains only white space, or contains at least one invalid character. + /// is . + /// In , the specified path, file name, or both exceed the system-defined maximum length. + /// is invalid or does not exist (for example, it is on an unmapped drive). + /// could not be opened. + /// -or- + /// is set to , but the file specified in already exists. + /// -or- + /// An unspecified I/O error occurred while opening the file. + /// specifies a directory. + /// -or- + /// The caller does not have the required permission to access the file specified in . + /// specifies an invalid value. + /// is set to , but the file specified in is not found. + /// contains an invalid format. + /// could not be interpreted as a zip archive. + /// -or- + /// is , but an entry is missing or corrupt and cannot be read. + /// -or- + /// is , but an entry is too large to fit into memory. public static ZipArchive Open(string archiveFileName, ZipArchiveMode mode) => Open(archiveFileName, mode, entryNameEncoding: null); - /// - /// Opens a ZipArchive on the specified archiveFileName in the specified ZipArchiveMode mode. - /// - /// - /// archiveFileName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. - /// path is null. - /// The specified 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. - /// The specified archiveFileName is invalid, (for example, it is on an unmapped drive). - /// An unspecified I/O error occurred while opening the file. - /// archiveFileName specified a directory. - /// -OR- The caller does not have the required permission. - /// mode specified an invalid value. - /// The file specified in archiveFileName was not found. - /// archiveFileName is in an invalid format. - /// 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. - /// - /// A string specifying the path on the filesystem to open the archive on. - /// The path is permitted to specify relative or absolute path information. - /// Relative path information is interpreted as relative to the current working directory. - /// See the description of the ZipArchiveMode enum. - /// 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 may be modified, and new entries may be created. - /// If the file exists and is not a Zip file, a ZipArchiveException will be thrown. - /// If the file exists and is empty or does not exist, a new Zip file will be created. - /// Note that creating a Zip file with the ZipArchiveMode.Create mode is more efficient when creating a new Zip file. - /// The encoding to use when reading or writing entry names in this ZipArchive. - /// /// NOTE: Specifying this parameter to values other than null is discouraged. - /// However, this may be necessary for interoperability with ZIP archive tools and libraries that do not 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) in order to decode the entry name. - /// 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) in order to decode the entry name. - /// - /// 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 in order to decode the entry name. - /// 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) in order to decode the entry name. - /// - /// Writing (saving) ZIP archive files: - /// If entryNameEncoding is not specified (== null): - /// - /// For entry names 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 in order to encode the entry name into bytes. - /// For entry names that do not 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 into bytes. - /// - /// If entryNameEncoding is specified (!= null): - /// - /// The specified entryNameEncoding will always be used to encode the entry names 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. - /// - /// Note that Unicode encodings other than UTF-8 may not be currently used for the entryNameEncoding, - /// otherwise an is thrown. - /// + /// Opens a zip archive at the specified path, in the specified mode, and by using the specified character encoding for entry names. + /// The path to the archive to open, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// One of the enumeration values that specifies the actions that are allowed on the entries in the opened archive. + /// 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. + /// The opened zip archive. + /// When you set the parameter to , the archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. Setting the parameter to is equivalent to calling the method. + /// When you set the parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. + /// When you set the 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 is set to , 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 is set to a value other than , entry names are decoded according to the following rules: + /// - When the language encoding flag is not set, the specified 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 is set to , 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 is set to a value other than , the specified 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. + /// -or- + /// is set to a Unicode encoding other than UTF-8. + /// is . + /// In , the specified path, file name, or both exceed the system-defined maximum length. + /// is invalid or does not exist (for example, it is on an unmapped drive). + /// could not be opened. + /// -or- + /// is set to , but the file specified in already exists. + /// -or- + /// An unspecified I/O error occurred while opening the file. + /// specifies a directory. + /// -or- + /// The caller does not have the required permission to access the file specified in . + /// specifies an invalid value. + /// is set to , but the file specified in is not found. + /// contains an invalid format. + /// could not be interpreted as a zip archive. + /// -or- + /// is , but an entry is missing or corrupt and cannot be read. + /// -or- + /// is , but an entry is too large to fit into memory. public static ZipArchive Open(string archiveFileName, ZipArchiveMode mode, Encoding? entryNameEncoding) { // Relies on FileStream's ctor for checking of archiveFileName @@ -193,160 +187,98 @@ public static ZipArchive Open(string archiveFileName, ZipArchiveMode mode, Encod } } - /// - ///

Creates a Zip archive at the path destinationArchiveFileName that contains the files and directories from - /// the directory specified by sourceDirectoryName. The directory structure is preserved in the archive, and a - /// recursive search is done for files to be archived. The archive must not exist. If the directory is empty, an empty - /// archive will be created. If a file in the directory cannot be added to the archive, the archive will be left incomplete - /// and invalid and the method will throw an exception. This method does not include the base directory into the archive. - /// If an error is encountered while adding files to the archive, this method will stop adding files and leave the archive - /// in an invalid state. The paths are permitted to specify relative or absolute path information. Relative path information - /// is interpreted as relative to the current working directory. If a file in the archive has data in the last write time - /// field that is not a valid Zip timestamp, an indicator value of 1980 January 1 at midnight will be used for the file's - /// last modified time.

- /// - ///

If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name.

- /// - ///

Since no CompressionLevel is specified, the default provided by the implementation of the underlying compression - /// algorithm will be used; the ZipArchive will not impose its own default. - /// (Currently, the underlying compression algorithm is provided by the System.IO.Compression.DeflateStream class.)

- /// - /// - /// sourceDirectoryName or destinationArchiveFileName is a zero-length - /// string, contains only whitespace, or contains one or more invalid characters as defined by - /// InvalidPathChars. - /// sourceDirectoryName or destinationArchiveFileName is null. - /// In sourceDirectoryName or destinationArchiveFileName, the specified - /// path, file name, or both exceed 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. - /// The path specified in sourceDirectoryName or destinationArchiveFileName - /// is invalid, (for example, it is on an unmapped drive). - /// -OR- The directory specified by sourceDirectoryName does not exist. - /// destinationArchiveFileName already exists. - /// -OR- An I/O error occurred while opening a file to be archived. - /// destinationArchiveFileName specified a directory. - /// -OR- The caller does not have the required permission. - /// sourceDirectoryName or destinationArchiveFileName is - /// in an invalid format. - /// - /// The path to the directory on the file system to be archived. - /// The name of the archive to be created. + /// Creates a zip archive that contains the files and directories from the specified directory. + /// The path to the directory to be archived, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// The path of the archive to be created, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// method overload. + /// 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. + /// [!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)] + /// ]]> + /// or is , contains only white space, or contains at least one invalid character. + /// or is . + /// In or , the specified path, file name, or both exceed the system-defined maximum length. + /// is invalid or does not exist (for example, it is on an unmapped drive). + /// already exists. + /// -or- + /// A file in the specified directory could not be opened. + /// -or- + /// An I/O error occurred while opening a file to be archived. + /// specifies a directory. + /// -or- + /// The caller does not have the required permission to access the directory specified in or the file specified in . + /// or contains an invalid format. + /// -or- + /// The zip archive does not support writing. public static void CreateFromDirectory(string sourceDirectoryName, string destinationArchiveFileName) => DoCreateFromDirectory(sourceDirectoryName, destinationArchiveFileName, compressionLevel: null, includeBaseDirectory: false, entryNameEncoding: null); - /// - ///

Creates a Zip archive at the path destinationArchiveFileName that contains the files and directories in the directory - /// specified by sourceDirectoryName. The directory structure is preserved in the archive, and a recursive search is - /// done for files to be archived. The archive must not exist. If the directory is empty, an empty archive will be created. - /// If a file in the directory cannot be added to the archive, the archive will be left incomplete and invalid and the - /// method will throw an exception. This method optionally includes the base directory in the archive. - /// If an error is encountered while adding files to the archive, this method will stop adding files and leave the archive - /// in an invalid state. The paths are permitted to specify relative or absolute path information. Relative path information - /// is interpreted as relative to the current working directory. If a file in the archive has data in the last write time - /// field that is not a valid Zip timestamp, an indicator value of 1980 January 1 at midnight will be used for the file's - /// last modified time.

- /// - ///

If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name.

- /// - ///

Since no CompressionLevel is specified, the default provided by the implementation of the underlying compression - /// algorithm will be used; the ZipArchive will not impose its own default. - /// (Currently, the underlying compression algorithm is provided by the System.IO.Compression.DeflateStream class.)

- /// - /// - /// sourceDirectoryName or destinationArchiveFileName is a zero-length - /// string, contains only whitespace, or contains one or more invalid characters as defined by - /// InvalidPathChars. - /// sourceDirectoryName or destinationArchiveFileName is null. - /// In sourceDirectoryName or destinationArchiveFileName, the - /// specified path, file name, or both exceed 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. - /// The path specified in sourceDirectoryName or - /// destinationArchiveFileName is invalid, (for example, it is on an unmapped drive). - /// -OR- The directory specified by sourceDirectoryName does not exist. - /// destinationArchiveFileName already exists. - /// -OR- An I/O error occurred while opening a file to be archived. - /// destinationArchiveFileName specified a directory. - /// -OR- The caller does not have the required permission. - /// sourceDirectoryName or destinationArchiveFileName - /// is in an invalid format. - /// - /// The path to the directory on the file system to be archived. - /// The name of the archive to be created. - /// The level of the compression (speed/memory vs. compressed size trade-off). - /// true to indicate that a directory named sourceDirectoryName should - /// be included at the root of the archive. false to indicate that the files and directories in sourceDirectoryName - /// should be included directly in the archive. + /// Creates a zip archive that contains the files and directories from the specified directory, uses the specified compression level, and optionally includes the base directory. + /// The path to the directory to be archived, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// The path of the archive to be created, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// One of the enumeration values that indicates whether to emphasize speed or compression effectiveness when creating the entry. + /// to include the directory name from at the root of the archive; to include only the contents of the directory. + /// 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. + /// [!code-csharp[System.IO.Compression.ZipFile#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.zipfile/cs/program2.cs#2)] + /// [!code-vb[System.IO.Compression.ZipFile#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.zipfile/vb/program2.vb#2)] + /// ]]> + /// or is , contains only white space, or contains at least one invalid character. + /// or is . + /// In or , the specified path, file name, or both exceed the system-defined maximum length. + /// is invalid or does not exist (for example, it is on an unmapped drive). + /// already exists. + /// -or- + /// A file in the specified directory could not be opened. + /// -or- + /// An I/O error occurred while opening a file to be archived. + /// specifies a directory. + /// -or- + /// The caller does not have the required permission to access the directory specified in or the file specified in . + /// or contains an invalid format. + /// -or- + /// The zip archive does not support writing. public static void CreateFromDirectory(string sourceDirectoryName, string destinationArchiveFileName, CompressionLevel compressionLevel, bool includeBaseDirectory) => DoCreateFromDirectory(sourceDirectoryName, destinationArchiveFileName, compressionLevel, includeBaseDirectory, entryNameEncoding: null); - /// - ///

Creates a Zip archive at the path destinationArchiveFileName that contains the files and directories in the directory - /// specified by sourceDirectoryName. The directory structure is preserved in the archive, and a recursive search is - /// done for files to be archived. The archive must not exist. If the directory is empty, an empty archive will be created. - /// If a file in the directory cannot be added to the archive, the archive will be left incomplete and invalid and the - /// method will throw an exception. This method optionally includes the base directory in the archive. - /// If an error is encountered while adding files to the archive, this method will stop adding files and leave the archive - /// in an invalid state. The paths are permitted to specify relative or absolute path information. Relative path information - /// is interpreted as relative to the current working directory. If a file in the archive has data in the last write time - /// field that is not a valid Zip timestamp, an indicator value of 1980 January 1 at midnight will be used for the file's - /// last modified time.

- /// - ///

If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name.

- /// - ///

Since no CompressionLevel is specified, the default provided by the implementation of the underlying compression - /// algorithm will be used; the ZipArchive will not impose its own default. - /// (Currently, the underlying compression algorithm is provided by the System.IO.Compression.DeflateStream class.)

- /// - /// - /// sourceDirectoryName or destinationArchiveFileName is a zero-length - /// string, contains only whitespace, or contains one or more invalid characters as defined by - /// InvalidPathChars. - /// sourceDirectoryName or destinationArchiveFileName is null. - /// In sourceDirectoryName or destinationArchiveFileName, the - /// specified path, file name, or both exceed 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. - /// The path specified in sourceDirectoryName or - /// destinationArchiveFileName is invalid, (for example, it is on an unmapped drive). - /// -OR- The directory specified by sourceDirectoryName does not exist. - /// destinationArchiveFileName already exists. - /// -OR- An I/O error occurred while opening a file to be archived. - /// destinationArchiveFileName specified a directory. - /// -OR- The caller does not have the required permission. - /// sourceDirectoryName or destinationArchiveFileName - /// is in an invalid format. - /// - /// The path to the directory on the file system to be archived. - /// The name of the archive to be created. - /// The level of the compression (speed/memory vs. compressed size trade-off). - /// true to indicate that a directory named sourceDirectoryName should - /// be included at the root of the archive. false to indicate that the files and directories in sourceDirectoryName - /// should be included directly in the archive. - /// The encoding to use when reading or writing entry names in this ZipArchive. - /// /// NOTE: Specifying this parameter to values other than null is discouraged. - /// However, this may be necessary for interoperability with ZIP archive tools and libraries that do not correctly support - /// UTF-8 encoding for entry names.
- /// This value is used as follows while creating the archive: - /// If entryNameEncoding is not specified (== null): - /// - /// For file names 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 of the corresponding entry, - /// and UTF-8 (Encoding.UTF8) will be used in order to encode the entry name into bytes. - /// For file names that do not 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 of the corresponding entry, - /// and the current system default code page (Encoding.Default) will be used to encode the entry names into bytes. - /// - /// If entryNameEncoding is specified (!= null): - /// - /// The specified entryNameEncoding will always be used to encode the entry names into bytes. - /// The language encoding flag (EFS) in the general purpose bit flag of the local file header for each entry will be set if and only - /// if the specified entryNameEncoding is a UTF-8 encoding. - /// - /// Note that Unicode encodings other than UTF-8 may not be currently used for the entryNameEncoding, - /// otherwise an is thrown. - /// + /// Creates a zip archive that contains the files and directories from the specified directory, uses the specified compression level and character encoding for entry names, and optionally includes the base directory. + /// The path to the directory to be archived, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// The path of the archive to be created, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// One of the enumeration values that indicates whether to emphasize speed or compression effectiveness when creating the entry. + /// to include the directory name from at the root of the archive; to include only the contents of the directory. + /// 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. + /// The directory structure from the file system is preserved in the archive. If the directory is empty, an empty archive is created. Use this method overload to specify the compression level and character encoding, and whether to include the base directory in the archive. + /// 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. + /// If is set to a value other than , the entry names are encoded by using the specified encoding. If the specified encoding is a UTF-8, the language encoding flag (in the general-purpose bit flag of the local file header) is set for each entry, + /// If is set to , the 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 UTF-8 is used to encode the entry name. + /// - For entry names that contain only ASCII characters, the language encoding flag is set, and the current system default code page is used to encode the entry names. + /// or is , contains only white space, or contains at least one invalid character. + /// -or- + /// is set to a Unicode encoding other than UTF-8. + /// or is . + /// In or , the specified path, file name, or both exceed the system-defined maximum length. + /// is invalid or does not exist (for example, it is on an unmapped drive). + /// already exists. + /// -or- + /// A file in the specified directory could not be opened. + /// -or- + /// An I/O error occurred while opening a file to be archived. + /// specifies a directory. + /// -or- + /// The caller does not have the required permission to access the directory specified in or the file specified in . + /// or contains an invalid format. + /// -or- + /// The zip archive does not support writing. public static void CreateFromDirectory(string sourceDirectoryName, string destinationArchiveFileName, CompressionLevel compressionLevel, bool includeBaseDirectory, Encoding? entryNameEncoding) => DoCreateFromDirectory(sourceDirectoryName, destinationArchiveFileName, compressionLevel, includeBaseDirectory, entryNameEncoding); diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs index 50e1717fc08a86..c02f82537d1174 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs @@ -8,183 +8,168 @@ namespace System.IO.Compression { + /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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 public static partial class ZipFile { - /// - /// Extracts all of the files in the specified archive to a directory on the file system. - /// The specified directory must not exist. This method will create all subdirectories and the specified directory. - /// If there is an error while extracting the archive, the archive will remain partially extracted. Each entry will - /// be extracted such that the extracted file has the same relative path to the destinationDirectoryName as the entry - /// has to the archive. The path is permitted to specify relative or absolute path information. Relative path information - /// is interpreted as relative to the current working directory. If a file to be archived has an invalid last modified - /// time, the first datetime representable in the Zip timestamp format (midnight on January 1, 1980) will be used. - /// - /// - /// sourceArchive or destinationDirectoryName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. - /// sourceArchive or destinationDirectoryName is null. - /// sourceArchive or destinationDirectoryName specifies a path, file name, - /// or both exceed 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. - /// The path specified by sourceArchive or destinationDirectoryName is invalid, - /// (for example, it is on an unmapped drive). - /// The directory specified by destinationDirectoryName already exists. - /// -or- An I/O error has occurred. -or- An archive entry?s name is zero-length, contains only whitespace, or contains one or - /// more invalid characters as defined by InvalidPathChars. -or- Extracting an archive entry would result in a file destination that is outside the destination directory (for example, because of parent directory accessors). -or- An archive entry has the same name as an already extracted entry from the same archive. - /// The caller does not have the required permission. - /// sourceArchive or destinationDirectoryName is in an invalid format. - /// sourceArchive was not found. - /// The archive specified by sourceArchive: Is not a valid ZipArchive - /// -or- An archive entry was not found or was corrupt. -or- An archive entry has been compressed using a compression method - /// that is not supported. - /// - /// The path to the archive on the file system that is to be extracted. - /// The path to the directory on the file system. The directory specified must not exist, but the directory that it is contained in must exist. + /// Extracts all the files in the specified zip archive to a directory on the file system. + /// The path to the archive that is to be extracted. + /// The path to the directory in which to place the extracted files, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// 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. + /// [!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)] + /// ]]> + /// or is , contains only white space, or contains at least one invalid character. + /// or is . + /// The specified path in or exceeds the system-defined maximum length. + /// The specified path is invalid (for example, it is on an unmapped drive). + /// The directory specified by already exists. + /// -or- + /// The name of an entry in the archive is , contains only white space, or contains at least one invalid character. + /// -or- + /// Extracting an archive entry would create a file that is outside the directory specified by . (For example, this might happen if the entry name contains parent directory accessors.) + /// -or- + /// An archive entry to extract has the same name as an entry that has already been extracted from the same archive. + /// The caller does not have the required permission to access the archive or the destination directory. + /// or contains an invalid format. + /// was not found. + /// The archive specified by is not a valid zip archive. + /// -or- + /// An archive entry was not found or was corrupt. + /// -or- + /// An archive entry was compressed by using a compression method that is not supported. public static void ExtractToDirectory(string sourceArchiveFileName, string destinationDirectoryName) => ExtractToDirectory(sourceArchiveFileName, destinationDirectoryName, entryNameEncoding: null, overwriteFiles: false); - /// - /// Extracts all of the files in the specified archive to a directory on the file system. - /// The specified directory must not exist. This method will create all subdirectories and the specified directory. - /// If there is an error while extracting the archive, the archive will remain partially extracted. Each entry will - /// be extracted such that the extracted file has the same relative path to the destinationDirectoryName as the entry - /// has to the archive. The path is permitted to specify relative or absolute path information. Relative path information - /// is interpreted as relative to the current working directory. If a file to be archived has an invalid last modified - /// time, the first datetime representable in the Zip timestamp format (midnight on January 1, 1980) will be used. - /// - /// - /// sourceArchive or destinationDirectoryName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. - /// sourceArchive or destinationDirectoryName is null. - /// sourceArchive or destinationDirectoryName specifies a path, file name, - /// or both exceed 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. - /// The path specified by sourceArchive or destinationDirectoryName is invalid, - /// (for example, it is on an unmapped drive). - /// The directory specified by destinationDirectoryName already exists. - /// -or- An I/O error has occurred. -or- An archive entry?s name is zero-length, contains only whitespace, or contains one or - /// more invalid characters as defined by InvalidPathChars. -or- Extracting an archive entry would result in a file destination that is outside the destination directory (for example, because of parent directory accessors). -or- An archive entry has the same name as an already extracted entry from the same archive. - /// The caller does not have the required permission. - /// sourceArchive or destinationDirectoryName is in an invalid format. - /// sourceArchive was not found. - /// The archive specified by sourceArchive: Is not a valid ZipArchive - /// -or- An archive entry was not found or was corrupt. -or- An archive entry has been compressed using a compression method - /// that is not supported. - /// - /// The path to the archive on the file system that is to be extracted. - /// The path to the directory on the file system. The directory specified must not exist, but the directory that it is contained in must exist. - /// True to indicate overwrite. + /// Extracts all of the files in the specified archive to a directory on the file system. + /// The path on the file system to the archive that is to be extracted. + /// The path to the destination directory on the file system. The directory specified must not exist, but the directory that it is contained in must exist. + /// to overwrite files; otherwise. + /// The specified directory must not exist. The method creates the specified directory and all subdirectories. + /// If there is an error while extracting the archive, the archive will remain partially extracted. + /// Each entry will be extracted such that the extracted file has the same relative path to the as the entry has to the archive. + /// The path can specify relative or absolute path information. A relative path is interpreted as relative to the current working directory. + /// If a file to be archived has an invalid last modified time, the first date and time representable in the Zip timestamp format (midnight on January 1, 1980) will be used. + /// or is a zero-length string, contains only whitespace, or contains one or more invalid characters as defined by . + /// or is . + /// or specifies a path, a file name, or both that exceed the system-defined maximum length. + /// The path specified by or is invalid (for example, it is on an unmapped drive). + /// The directory specified by already exists. + /// -or- + /// An I/O error has occurred. + /// -or- + /// The name of a is zero-length, contains only whitespace, or contains one or more invalid characters as defined by . + /// -or- + /// Extracting a would result in a file destination that is outside the destination directory (for example, because of parent directory accessors). + /// -or- + /// A has the same name as an already extracted entry from the same archive. + /// The caller does not have the required permission. + /// or is in an invalid format. + /// was not found. + /// The archive specified by is not a valid . + /// -or- + /// A was not found or was corrupt. + /// -or- + /// A has been compressed using a compression method that is not supported. public static void ExtractToDirectory(string sourceArchiveFileName, string destinationDirectoryName, bool overwriteFiles) => ExtractToDirectory(sourceArchiveFileName, destinationDirectoryName, entryNameEncoding: null, overwriteFiles: overwriteFiles); - /// - /// Extracts all of the files in the specified archive to a directory on the file system. - /// The specified directory must not exist. This method will create all subdirectories and the specified directory. - /// If there is an error while extracting the archive, the archive will remain partially extracted. Each entry will - /// be extracted such that the extracted file has the same relative path to the destinationDirectoryName as the entry - /// has to the archive. The path is permitted to specify relative or absolute path information. Relative path information - /// is interpreted as relative to the current working directory. If a file to be archived has an invalid last modified - /// time, the first datetime representable in the Zip timestamp format (midnight on January 1, 1980) will be used. - /// - /// - /// sourceArchive or destinationDirectoryName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. - /// sourceArchive or destinationDirectoryName is null. - /// sourceArchive or destinationDirectoryName specifies a path, file name, - /// or both exceed 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. - /// The path specified by sourceArchive or destinationDirectoryName is invalid, - /// (for example, it is on an unmapped drive). - /// The directory specified by destinationDirectoryName already exists. - /// -or- An I/O error has occurred. -or- An archive entry?s name is zero-length, contains only whitespace, or contains one or - /// more invalid characters as defined by InvalidPathChars. -or- Extracting an archive entry would result in a file destination that is outside the destination directory (for example, because of parent directory accessors). -or- An archive entry has the same name as an already extracted entry from the same archive. - /// The caller does not have the required permission. - /// sourceArchive or destinationDirectoryName is in an invalid format. - /// sourceArchive was not found. - /// The archive specified by sourceArchive: Is not a valid ZipArchive - /// -or- An archive entry was not found or was corrupt. -or- An archive entry has been compressed using a compression method - /// that is not supported. - /// - /// The path to the archive on the file system that is to be extracted. - /// The path to the directory on the file system. The directory specified must not exist, but the directory that it is contained in must exist. - /// The encoding to use when reading or writing entry names in this ZipArchive. - /// /// NOTE: Specifying this parameter to values other than null is discouraged. - /// However, this may be necessary for interoperability with ZIP archive tools and libraries that do not correctly support - /// UTF-8 encoding for entry names.
- /// This value is used as follows: - /// 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) in order to decode the entry name. - /// 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) in order to decode the entry name. - /// - /// 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 in order to decode the entry name. - /// 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) in order to decode the entry name. - /// - /// Note that Unicode encodings other than UTF-8 may not be currently used for the entryNameEncoding, - /// otherwise an is thrown. - /// + /// Extracts all the files in the specified zip archive to a directory on the file system and uses the specified character encoding for entry names. + /// The path to the archive that is to be extracted. + /// The path to the directory in which to place the extracted files, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. + /// 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. + /// This method creates the specified directory and all subdirectories. The destination directory cannot already exist. Exceptions related to validating the paths in the or 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 as its source entry has to the root of the archive. + /// If is set to a value other than , entry names are decoded according to the following rules: + /// - For entry names where the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the entry names are decoded by using the specified encoding. + /// - For entries where the language encoding flag is set, the entry names are decoded by using UTF-8. + /// If is set to , entry names are decoded according to the following rules: + /// - For entries where the language encoding flag (in the general-purpose bit flag of the local file header) is not set, entry names are decoded by using the current system default code page. + /// - For entries where the language encoding flag is set, the entry names are decoded by using UTF-8. + /// or is , contains only white space, or contains at least one invalid character. + /// -or- + /// is set to a Unicode encoding other than UTF-8. + /// or is . + /// The specified path in or exceeds the system-defined maximum length. + /// The specified path is invalid (for example, it is on an unmapped drive). + /// The directory specified by already exists. + /// -or- + /// The name of an entry in the archive is , contains only white space, or contains at least one invalid character. + /// -or- + /// Extracting an archive entry would create a file that is outside the directory specified by . (For example, this might happen if the entry name contains parent directory accessors.) + /// -or- + /// An archive entry to extract has the same name as an entry that has already been extracted from the same archive. + /// The caller does not have the required permission to access the archive or the destination directory. + /// or contains an invalid format. + /// was not found. + /// The archive specified by is not a valid zip archive. + /// -or- + /// An archive entry was not found or was corrupt. + /// -or- + /// An archive entry was compressed by using a compression method that is not supported. public static void ExtractToDirectory(string sourceArchiveFileName, string destinationDirectoryName, Encoding? entryNameEncoding) => ExtractToDirectory(sourceArchiveFileName, destinationDirectoryName, entryNameEncoding: entryNameEncoding, overwriteFiles: false); - /// - /// Extracts all of the files in the specified archive to a directory on the file system. - /// The specified directory must not exist. This method will create all subdirectories and the specified directory. - /// If there is an error while extracting the archive, the archive will remain partially extracted. Each entry will - /// be extracted such that the extracted file has the same relative path to the destinationDirectoryName as the entry - /// has to the archive. The path is permitted to specify relative or absolute path information. Relative path information - /// is interpreted as relative to the current working directory. If a file to be archived has an invalid last modified - /// time, the first datetime representable in the Zip timestamp format (midnight on January 1, 1980) will be used. - /// - /// - /// sourceArchive or destinationDirectoryName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. - /// sourceArchive or destinationDirectoryName is null. - /// sourceArchive or destinationDirectoryName specifies a path, file name, - /// or both exceed 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. - /// The path specified by sourceArchive or destinationDirectoryName is invalid, - /// (for example, it is on an unmapped drive). - /// The directory specified by destinationDirectoryName already exists. - /// -or- An I/O error has occurred. -or- An archive entry?s name is zero-length, contains only whitespace, or contains one or - /// more invalid characters as defined by InvalidPathChars. -or- Extracting an archive entry would result in a file destination that is outside the destination directory (for example, because of parent directory accessors). -or- An archive entry has the same name as an already extracted entry from the same archive. - /// The caller does not have the required permission. - /// sourceArchive or destinationDirectoryName is in an invalid format. - /// sourceArchive was not found. - /// The archive specified by sourceArchive: Is not a valid ZipArchive - /// -or- An archive entry was not found or was corrupt. -or- An archive entry has been compressed using a compression method - /// that is not supported. - /// - /// The path to the archive on the file system that is to be extracted. - /// The path to the directory on the file system. The directory specified must not exist, but the directory that it is contained in must exist. - /// True to indicate overwrite. - /// The encoding to use when reading or writing entry names in this ZipArchive. - /// /// NOTE: Specifying this parameter to values other than null is discouraged. - /// However, this may be necessary for interoperability with ZIP archive tools and libraries that do not correctly support - /// UTF-8 encoding for entry names.
- /// This value is used as follows: - /// 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) in order to decode the entry name. - /// 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) in order to decode the entry name. - /// - /// 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 in order to decode the entry name. - /// 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) in order to decode the entry name. - /// - /// Note that Unicode encodings other than UTF-8 may not be currently used for the entryNameEncoding, - /// otherwise an is thrown. - /// + /// Extracts all of the files in the specified archive to a directory on the file system. + /// The path on the file system to the archive that is to be extracted. + /// The path to the destination directory on the file system. The directory specified must not exist, but the directory that it is contained in must exist. + /// The encoding to use when reading entry names in this . + /// to overwrite files; otherwise. + /// The specified directory must not exist. This method will create the specified directory and all subdirectories. + /// If there is an error while extracting the archive, the archive will remain partially extracted. + /// Each entry will be extracted such that the extracted file has the same relative path to the as the entry has to the archive. + /// The path can specify relative or absolute path information. A relative path is interpreted as relative to the current working directory. + /// If a file to be archived has an invalid last modified time, the first date and time representable in the Zip timestamp format (midnight on January 1, 1980) will be used. + /// or is a zero-length string, contains only whitespace, or contains one or more invalid characters as defined by . + /// -or- + /// is set to a Unicode encoding other than UTF-8. + /// or is . + /// or specifies a path, a file name, or both that exceed the system-defined maximum length. + /// The path specified by or is invalid (for example, it is on an unmapped drive). + /// The directory specified by already exists. + /// -or- + /// An I/O error has occurred. + /// -or- + /// The name of a is zero-length, contains only whitespace, or contains one or more invalid characters as defined by . + /// -or- + /// Extracting a would result in a file destination that is outside the destination directory (for example, because of parent directory accessors). + /// -or- + /// A has the same name as an already extracted entry from the same archive. + /// The caller does not have the required permission. + /// or is in an invalid format. + /// was not found. + /// The archive specified by is not a valid . + /// -or- + /// An archive entry was not found or was corrupt. + /// -or- + /// An archive entry has been compressed using a compression method that is not supported. public static void ExtractToDirectory(string sourceArchiveFileName, string destinationDirectoryName, Encoding? entryNameEncoding, bool overwriteFiles) { if (sourceArchiveFileName == null) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs index 00d82c242b0a67..0b1c433d70c19f 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs @@ -5,74 +5,89 @@ namespace System.IO.Compression { + /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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)] + /// ]]> [EditorBrowsable(EditorBrowsableState.Never)] public static partial class ZipFileExtensions { - /// - ///

Adds a file from the file system to the archive under the specified entry name. - /// The new entry in the archive will contain the contents of the file. - /// The last write time of the archive entry is set to the last write time of the file on the file system. - /// If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name. - /// If the specified source file has an invalid last modified time, the first datetime representable in the Zip timestamp format - /// (midnight on January 1, 1980) will be used.

- /// - ///

If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name.

- /// - ///

Since no CompressionLevel is specified, the default provided by the implementation of the underlying compression - /// algorithm will be used; the ZipArchive will not impose its own default. - /// (Currently, the underlying compression algorithm is provided by the System.IO.Compression.DeflateStream class.)

- /// - /// - /// sourceFileName is a zero-length string, contains only whitespace, or contains one or more - /// invalid characters as defined by InvalidPathChars. -or- entryName is a zero-length string. - /// sourceFileName or entryName is null. - /// In sourceFileName, the specified path, file name, or both exceed 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. - /// The specified sourceFileName is invalid, (for example, it is on an unmapped drive). - /// An I/O error occurred while opening the file specified by sourceFileName. - /// sourceFileName specified a directory. -or- The caller does not have the - /// required permission. - /// The file specified in sourceFileName was not found. - /// sourceFileName is in an invalid format or the ZipArchive does not support writing. - /// The ZipArchive has already been closed. - /// + /// Archives a file by compressing it and adding it to the zip archive. /// The zip archive to add the file to. - /// The path to the file on the file system to be copied from. The path is permitted to specify - /// relative or absolute path information. Relative path information is interpreted as relative to the current working directory. - /// The name of the entry to be created. - /// A wrapper for the newly created entry. + /// The path to the file to be archived. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. + /// The name of the entry to create in the zip archive. + /// A wrapper for the new entry in the zip archive. + /// property of the entry is set to the last time the file on the file system was changed. + /// When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. + /// ## Examples + /// The following example shows how to create a new entry in a zip archive from an existing file. + /// [!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)] + /// ]]> + /// is , contains only white space, or contains at least one invalid character. + /// -or- + /// is . + /// or is . + /// In , the specified path, file name, or both exceed the system-defined maximum length. + /// is invalid (for example, it is on an unmapped drive). + /// The file specified by cannot be opened, or is too large to be updated (current limit is ). + /// specifies a directory. + /// -or- + /// The caller does not have the required permission to access the file specified by . + /// The file specified by is not found. + /// The parameter is in an invalid format. + /// -or- + /// The zip archive does not support writing. + /// The zip archive has been disposed. public static ZipArchiveEntry CreateEntryFromFile(this ZipArchive destination, string sourceFileName, string entryName) => DoCreateEntryFromFile(destination, sourceFileName, entryName, null); - - /// - ///

Adds a file from the file system to the archive under the specified entry name. - /// The new entry in the archive will contain the contents of the file. - /// The last write time of the archive entry is set to the last write time of the file on the file system. - /// If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name. - /// If the specified source file has an invalid last modified time, the first datetime representable in the Zip timestamp format - /// (midnight on January 1, 1980) will be used.

- ///

If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name.

- /// - /// sourceFileName is a zero-length string, contains only whitespace, or contains one or more - /// invalid characters as defined by InvalidPathChars. -or- entryName is a zero-length string. - /// sourceFileName or entryName is null. - /// In sourceFileName, the specified path, file name, or both exceed 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. - /// The specified sourceFileName is invalid, (for example, it is on an unmapped drive). - /// An I/O error occurred while opening the file specified by sourceFileName. - /// sourceFileName specified a directory. - /// -or- The caller does not have the required permission. - /// The file specified in sourceFileName was not found. - /// sourceFileName is in an invalid format or the ZipArchive does not support writing. - /// The ZipArchive has already been closed. - /// + /// Archives a file by compressing it using the specified compression level and adding it to the zip archive. /// The zip archive to add the file to. - /// The path to the file on the file system to be copied from. The path is permitted to specify relative - /// or absolute path information. Relative path information is interpreted as relative to the current working directory. - /// The name of the entry to be created. - /// The level of the compression (speed/memory vs. compressed size trade-off). - /// A wrapper for the newly created entry. + /// The path to the file to be archived. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. + /// The name of the entry to create in the zip archive. + /// One of the enumeration values that indicates whether to emphasize speed or compression effectiveness when creating the entry. + /// A wrapper for the new entry in the zip archive. + /// property of the entry is set to the last time the file on the file system was changed. + /// When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. + /// ## Examples + /// The following example shows how to create a new entry in a zip archive from an existing file, and specify the compression level. + /// [!code-csharp[System.IO.Compression.ZipArchive#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program4.cs#4)] + /// [!code-vb[System.IO.Compression.ZipArchive#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program4.vb#4)] + /// ]]> + /// is , contains only white space, or contains at least one invalid character. + /// -or- + /// is . + /// or is . + /// is invalid (for example, it is on an unmapped drive). + /// In , the specified path, file name, or both exceed the system-defined maximum length. + /// The file specified by cannot be opened, or is too large to be updated (current limit is ). + /// specifies a directory. + /// -or- + /// The caller does not have the required permission to access the file specified by . + /// The file specified by is not found. + /// The parameter is in an invalid format. + /// -or- + /// The zip archive does not support writing. + /// The zip archive has been disposed. public static ZipArchiveEntry CreateEntryFromFile(this ZipArchive destination, string sourceFileName, string entryName, CompressionLevel compressionLevel) => DoCreateEntryFromFile(destination, sourceFileName, entryName, compressionLevel); diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs index 3dd751dce8ddf6..1af5dea58b4024 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs @@ -5,66 +5,80 @@ namespace System.IO.Compression { + /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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)] + /// ]]> public static partial class ZipFileExtensions { - /// - /// Extracts all of the files in the archive to a directory on the file system. The specified directory may already exist. - /// This method will create all subdirectories and the specified directory if necessary. - /// If there is an error while extracting the archive, the archive will remain partially extracted. - /// Each entry will be extracted such that the extracted file has the same relative path to destinationDirectoryName as the - /// entry has to the root of the archive. If a file to be archived has an invalid last modified time, the first datetime - /// representable in the Zip timestamp format (midnight on January 1, 1980) will be used. - /// - /// - /// destinationDirectoryName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. - /// destinationDirectoryName is null. - /// The specified path, file name, or both exceed 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. - /// The specified path is invalid, (for example, it is on an unmapped drive). - /// An archive entry?s name is zero-length, contains only whitespace, or contains one or more invalid - /// characters as defined by InvalidPathChars. -or- Extracting an archive entry would have resulted in a destination - /// file that is outside destinationDirectoryName (for example, if the entry name contains parent directory accessors). - /// -or- An archive entry has the same name as an already extracted entry from the same archive. - /// The caller does not have the required permission. - /// destinationDirectoryName is in an invalid format. - /// An archive entry was not found or was corrupt. - /// -or- An archive entry has been compressed using a compression method that is not supported. + /// Extracts all the files in the zip archive to a directory on the file system. /// The zip archive to extract files from. - /// The path to the directory on the file system. - /// The directory specified must not exist. The path is permitted to specify relative or absolute path information. - /// Relative path information is interpreted as relative to the current working directory. + /// The path to the directory to place the extracted files in. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. + /// exception. The method also creates subdirectories that reflect the hierarchy in the zip archive. 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 + /// The following example shows how to create a new entry in a zip archive from an existing file, and extract the archive to a new directory. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. + /// [!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)] + /// ]]> + /// is , contains only white space, or contains at least one invalid character. + /// is . + /// The specified path exceeds the system-defined maximum length. + /// The specified path is invalid (for example, it is on an unmapped drive). + /// The directory specified by already exists. + /// -or- + /// The name of an entry in the archive is , contains only white space, or contains at least one invalid character. + /// -or- + /// Extracting an entry from the archive would create a file that is outside the directory specified by . (For example, this might happen if the entry name contains parent directory accessors.) + /// -or- + /// Two or more entries in the archive have the same name. + /// The caller does not have the required permission to write to the destination directory. + /// contains an invalid format. + /// An archive entry cannot be found or is corrupt. + /// -or- + /// An archive entry was compressed by using a compression method that is not supported. public static void ExtractToDirectory(this ZipArchive source, string destinationDirectoryName) => ExtractToDirectory(source, destinationDirectoryName, overwriteFiles: false); - /// - /// Extracts all of the files in the archive to a directory on the file system. The specified directory may already exist. - /// This method will create all subdirectories and the specified directory if necessary. + /// Extracts all of the files in the archive to a directory on the file system. + /// The to extract. + /// The path to the destination directory on the file system. The path can be relative or absolute. A relative path is interpreted as relative to the current working directory. + /// to indicate that existing files are to be overwritten; otherwise. + /// The specified directory may already exist. This method will create the specified directory and all subdirectories if necessary. /// If there is an error while extracting the archive, the archive will remain partially extracted. - /// Each entry will be extracted such that the extracted file has the same relative path to destinationDirectoryName as the - /// entry has to the root of the archive. If a file to be archived has an invalid last modified time, the first datetime - /// representable in the Zip timestamp format (midnight on January 1, 1980) will be used. - /// - /// - /// destinationDirectoryName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. - /// destinationDirectoryName is null. - /// The specified path, file name, or both exceed 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. - /// The specified path is invalid, (for example, it is on an unmapped drive). - /// An archive entry?s name is zero-length, contains only whitespace, or contains one or more invalid - /// characters as defined by InvalidPathChars. -or- Extracting an archive entry would have resulted in a destination - /// file that is outside destinationDirectoryName (for example, if the entry name contains parent directory accessors). - /// -or- An archive entry has the same name as an already extracted entry from the same archive. - /// The caller does not have the required permission. - /// destinationDirectoryName is in an invalid format. - /// An archive entry was not found or was corrupt. - /// -or- An archive entry has been compressed using a compression method that is not supported. - /// The zip archive to extract files from. - /// The path to the directory on the file system. - /// The directory specified must not exist. The path is permitted to specify relative or absolute path information. - /// Relative path information is interpreted as relative to the current working directory. - /// True to indicate overwrite. + /// Each entry will be extracted such that the extracted file has the same relative path to as the entry has to the root of the archive. + /// If a file to be archived has an invalid last modified time, the first date and time representable in the Zip timestamp format (midnight on January 1, 1980) will be used. + /// is a zero-length string, contains only whitespace, + /// or contains one or more invalid characters as defined by . + /// is . + /// The specified path, file name, or both exceed the system-defined maximum length. + /// The specified path is invalid, (for example, it is on an unmapped drive). + /// The name of a is zero-length, contains only whitespace, or contains one or more invalid characters as defined by . + /// -or- + /// Extracting a would have resulted in a destination file that is outside (for example, if the entry name contains parent directory accessors). + /// -or- + /// A has the same name as an already extracted entry from the same archive. + /// The caller does not have the required permission. + /// is in an invalid format. + /// A was not found or was corrupt. + /// -or- + /// A has been compressed using a compression method that is not supported. public static void ExtractToDirectory(this ZipArchive source, string destinationDirectoryName, bool overwriteFiles) { if (source == null) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs index cad1a12c5a485b..4b5195f0c7e0e7 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs @@ -5,65 +5,97 @@ namespace System.IO.Compression { + /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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)] + /// ]]> public static partial class ZipFileExtensions { - /// - /// Creates a file on the file system with the entry?s contents and the specified name. The last write time of the file is set to the - /// entry?s last write time. This method does not allow overwriting of an existing file with the same name. Attempting to extract explicit - /// directories (entries with names that end in directory separator characters) will not result in the creation of a directory. - /// - /// - /// The caller does not have the required permission. - /// destinationFileName is a zero-length string, contains only whitespace, or contains one or more - /// invalid characters as defined by InvalidPathChars. -or- destinationFileName specifies a directory. - /// destinationFileName is null. - /// The specified path, file name, or both exceed 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. - /// The path specified in destinationFileName is invalid (for example, it is on - /// an unmapped drive). - /// destinationFileName already exists. - /// -or- An I/O error has occurred. -or- The entry is currently open for writing. - /// -or- The entry has been deleted from the archive. - /// destinationFileName is in an invalid format - /// -or- The ZipArchive that this entry belongs to was opened in a write-only mode. - /// The entry is missing from the archive or is corrupt and cannot be read - /// -or- The entry has been compressed using a compression method that is not supported. - /// The ZipArchive that this entry belongs to has been disposed. + /// Extracts an entry in the zip archive to a file. /// The zip archive entry to extract a file from. - /// The name of the file that will hold the contents of the entry. - /// The path is permitted to specify relative or absolute path information. - /// Relative path information is interpreted as relative to the current working directory. + /// The path of the file to create from the contents of the entry. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. + /// exception. To overwrite an existing file, use the method overload instead. + /// The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. + /// You cannot use this method to extract a directory; use the method instead. + /// ## Examples + /// The following example shows how to iterate through the contents of a zip archive file 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)] + /// ]]> + /// is a zero-length string, contains only white space, or contains one or more invalid characters as defined by . + /// -or- + /// specifies a directory. + /// is . + /// The specified path, file name, or both exceed the system-defined maximum length. + /// The specified path is invalid (for example, it is on an unmapped drive). + /// already exists. + /// -or- + /// An I/O error occurred. + /// -or- + /// The entry is currently open for writing. + /// -or- + /// The entry has been deleted from the archive. + /// The caller does not have the required permission to create the new file. + /// The entry is missing from the archive, or is corrupt and cannot be read. + /// -or- + /// The entry has been compressed by using a compression method that is not supported. + /// The zip archive that this entry belongs to has been disposed. + /// is in an invalid format. + /// -or- + /// The zip archive for this entry was opened in mode, which does not permit the retrieval of entries. public static void ExtractToFile(this ZipArchiveEntry source, string destinationFileName) => ExtractToFile(source, destinationFileName, false); - /// - /// Creates a file on the file system with the entry?s contents and the specified name. - /// The last write time of the file is set to the entry?s last write time. - /// This method does allows overwriting of an existing file with the same name. - /// - /// - /// The caller does not have the required permission. - /// destinationFileName is a zero-length string, contains only whitespace, - /// or contains one or more invalid characters as defined by InvalidPathChars. -or- destinationFileName specifies a directory. - /// destinationFileName is null. - /// The specified path, file name, or both exceed 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. - /// The path specified in destinationFileName is invalid - /// (for example, it is on an unmapped drive). - /// destinationFileName exists and overwrite is false. - /// -or- An I/O error has occurred. - /// -or- The entry is currently open for writing. - /// -or- The entry has been deleted from the archive. - /// destinationFileName is in an invalid format - /// -or- The ZipArchive that this entry belongs to was opened in a write-only mode. - /// The entry is missing from the archive or is corrupt and cannot be read - /// -or- The entry has been compressed using a compression method that is not supported. - /// The ZipArchive that this entry belongs to has been disposed. + /// Extracts an entry in the zip archive to a file, and optionally overwrites an existing file that has the same name. /// The zip archive entry to extract a file from. - /// The name of the file that will hold the contents of the entry. - /// The path is permitted to specify relative or absolute path information. - /// Relative path information is interpreted as relative to the current working directory. - /// True to indicate overwrite. + /// The path of the file to create from the contents of the entry. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. + /// to overwrite an existing file that has the same name as the destination file; otherwise, . + /// property. + /// You cannot use this method to extract a directory; use the method instead. + /// ## Examples + /// The following example shows how to iterate through the contents of a zip archive file, and extract files that have a .txt extension. It overwrites an existing file that has the same name in the destination folder. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. + /// [!code-csharp[System.IO.Compression.ZipArchive#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program2.cs#2)] + /// [!code-vb[System.IO.Compression.ZipArchive#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program2.vb#2)] + /// ]]> + /// is a zero-length string, contains only white space, or contains one or more invalid characters as defined by . + /// -or- + /// specifies a directory. + /// is . + /// The specified path, file name, or both exceed the system-defined maximum length. + /// The specified path is invalid (for example, it is on an unmapped drive). + /// already exists and is . + /// -or- + /// An I/O error occurred. + /// -or- + /// The entry is currently open for writing. + /// -or- + /// The entry has been deleted from the archive. + /// The caller does not have the required permission to create the new file. + /// The entry is missing from the archive or is corrupt and cannot be read. + /// -or- + /// The entry has been compressed by using a compression method that is not supported. + /// The zip archive that this entry belongs to has been disposed. + /// is in an invalid format. + /// -or- + /// The zip archive for this entry was opened in mode, which does not permit the retrieval of entries. public static void ExtractToFile(this ZipArchiveEntry source, string destinationFileName, bool overwrite) { if (source == null) From 2d29312ced2dd7bf1fc9f81d56d849a256b3fb32 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Mon, 22 Feb 2021 16:42:31 -0800 Subject: [PATCH 2/8] Fix renamed parameter. --- .../Compression/ZipFileExtensions.ZipArchive.Extract.cs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs index 1af5dea58b4024..96310672cc2025 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs @@ -64,18 +64,18 @@ public static void ExtractToDirectory(this ZipArchive source, string destination /// If there is an error while extracting the archive, the archive will remain partially extracted. /// Each entry will be extracted such that the extracted file has the same relative path to as the entry has to the root of the archive. /// If a file to be archived has an invalid last modified time, the first date and time representable in the Zip timestamp format (midnight on January 1, 1980) will be used. - /// is a zero-length string, contains only whitespace, + /// is a zero-length string, contains only whitespace, /// or contains one or more invalid characters as defined by . - /// is . + /// is . /// The specified path, file name, or both exceed the system-defined maximum length. /// The specified path is invalid, (for example, it is on an unmapped drive). /// The name of a is zero-length, contains only whitespace, or contains one or more invalid characters as defined by . /// -or- - /// Extracting a would have resulted in a destination file that is outside (for example, if the entry name contains parent directory accessors). + /// Extracting a would have resulted in a destination file that is outside (for example, if the entry name contains parent directory accessors). /// -or- /// A has the same name as an already extracted entry from the same archive. /// The caller does not have the required permission. - /// is in an invalid format. + /// is in an invalid format. /// A was not found or was corrupt. /// -or- /// A has been compressed using a compression method that is not supported. From 58b7014b49260d4a94e25a9a9b89a1e4600e91c8 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Mon, 22 Feb 2021 16:50:36 -0800 Subject: [PATCH 3/8] Update include links to lengthy remarks --- .../System/IO/Compression/ZipFile.Create.cs | 40 ++----------------- .../System/IO/Compression/ZipFile.Extract.cs | 24 +---------- .../ZipFileExtensions.ZipArchive.Create.cs | 18 +-------- .../ZipFileExtensions.ZipArchive.Extract.cs | 18 +-------- ...pFileExtensions.ZipArchiveEntry.Extract.cs | 18 +-------- 5 files changed, 8 insertions(+), 110 deletions(-) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs index 12d67e49224b78..a3764420746d96 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs @@ -10,29 +10,7 @@ namespace System.IO.Compression { /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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)] + /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipFile/ZipFile.md)] /// ]]> /// How to: Add or Remove References By Using the Reference Manager public static partial class ZipFile @@ -102,19 +80,9 @@ public static partial class ZipFile /// One of the enumeration values that specifies the actions that are allowed on the entries in the opened archive. /// 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. /// The opened zip archive. - /// When you set the parameter to , the archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. Setting the parameter to is equivalent to calling the method. - /// When you set the parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. - /// When you set the 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 is set to , 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 is set to a value other than , entry names are decoded according to the following rules: - /// - When the language encoding flag is not set, the specified 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 is set to , 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 is set to a value other than , the specified 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. /// -or- /// is set to a Unicode encoding other than UTF-8. diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs index c02f82537d1174..01777aa021b795 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs @@ -10,29 +10,7 @@ namespace System.IO.Compression { /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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)] + /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipFile/ZipFile.md)] /// ]]> /// How to: Add or Remove References By Using the Reference Manager public static partial class ZipFile diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs index 0b1c433d70c19f..ed2e9c24c7d7fc 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs @@ -7,23 +7,7 @@ namespace System.IO.Compression { /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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)] + /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md)] /// ]]> [EditorBrowsable(EditorBrowsableState.Never)] public static partial class ZipFileExtensions diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs index 96310672cc2025..7d1e7080d04b3a 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs @@ -7,23 +7,7 @@ namespace System.IO.Compression { /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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)] + /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md)] /// ]]> public static partial class ZipFileExtensions { diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs index 4b5195f0c7e0e7..0fc7aafee2f35d 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs @@ -7,23 +7,7 @@ namespace System.IO.Compression { /// 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 [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. Therefore, the and classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] 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)] + /// [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md)] /// ]]> public static partial class ZipFileExtensions { From 69369f44c7790f84b3ed5ff3055488a95f7be77c Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Tue, 23 Feb 2021 17:27:29 -0800 Subject: [PATCH 4/8] GenerateDocumentationFile csproj --- .../src/System.IO.Compression.ZipFile.csproj | 1 + 1 file changed, 1 insertion(+) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System.IO.Compression.ZipFile.csproj b/src/libraries/System.IO.Compression.ZipFile/src/System.IO.Compression.ZipFile.csproj index 366de34f8b92df..cf2cf7b18e8230 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System.IO.Compression.ZipFile.csproj +++ b/src/libraries/System.IO.Compression.ZipFile/src/System.IO.Compression.ZipFile.csproj @@ -3,6 +3,7 @@ true $(NetCoreAppCurrent) enable + true From fbe486a50b6f33a176e23c4211c339f2347f0bb9 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Wed, 24 Feb 2021 17:21:15 -0800 Subject: [PATCH 5/8] Remove unrelated article. --- .../src/System/IO/Compression/ZipFile.Create.cs | 1 - .../src/System/IO/Compression/ZipFile.Extract.cs | 1 - 2 files changed, 2 deletions(-) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs index a3764420746d96..92c39b055aec03 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs @@ -12,7 +12,6 @@ namespace System.IO.Compression /// - /// How to: Add or Remove References By Using the Reference Manager public static partial class ZipFile { /// Opens a zip archive for reading at the specified path. diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs index 01777aa021b795..d7597b16f2b8d7 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs @@ -12,7 +12,6 @@ namespace System.IO.Compression /// - /// How to: Add or Remove References By Using the Reference Manager public static partial class ZipFile { /// Extracts all the files in the specified zip archive to a directory on the file system. From 9c3e5c26c7431512833ba8e0dfb088d427c00ed7 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 00:11:18 -0800 Subject: [PATCH 6/8] Wrap in CDATA only the sections that can't be converted to xml. The rest is xml. --- .../System/IO/Compression/ZipFile.Create.cs | 49 +++++++++---------- .../System/IO/Compression/ZipFile.Extract.cs | 10 ++-- .../ZipFileExtensions.ZipArchive.Create.cs | 22 ++++----- .../ZipFileExtensions.ZipArchive.Extract.cs | 9 ++-- ...pFileExtensions.ZipArchiveEntry.Extract.cs | 24 +++++---- 5 files changed, 53 insertions(+), 61 deletions(-) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs index 92c39b055aec03..d90adcbff652ea 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs @@ -12,18 +12,18 @@ namespace System.IO.Compression /// + /// How to: Add or Remove References By Using the Reference Manager public static partial class ZipFile { /// Opens a zip archive for reading at the specified path. /// The path to the archive to open, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. /// The opened zip archive. - /// method and setting the `mode` parameter to . The archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. - /// ## Examples - /// The following example shows how to open a zip archive for reading. + /// This method is equivalent to calling the method and setting the `mode` parameter to . The archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. + /// The following example shows how to open a zip archive for reading. + /// + /// ]]> /// is , contains only white space, or contains at least one invalid character. /// is . /// In , the specified path, file name, or both exceed the system-defined maximum length. @@ -43,15 +43,14 @@ public static partial class ZipFile /// The path to the archive to open, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. /// One of the enumeration values that specifies the actions which are allowed on the entries in the opened archive. /// The opened zip archive. - /// , the archive is opened with from the enumeration 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. - /// ## Examples - /// The following example shows how to open a zip archive in the update mode and add an entry to the archive. + /// When you set the parameter to , the archive is opened with from the enumeration as the file mode value. If the archive does not exist, a exception is thrown. Setting the parameter to is equivalent to calling the method. + /// When you set the parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. + /// When you set the 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. + /// The following example shows how to open a zip archive in the update mode and add an entry to the archive. + /// + /// ]]> /// is , contains only white space, or contains at least one invalid character. /// is . /// In , the specified path, file name, or both exceed the system-defined maximum length. @@ -157,15 +156,14 @@ public static ZipArchive Open(string archiveFileName, ZipArchiveMode mode, Encod /// Creates a zip archive that contains the files and directories from the specified directory. /// The path to the directory to be archived, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. /// The path of the archive to be created, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. - /// method overload. - /// 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. + /// The directory structure from the file system is preserved in the archive. If the directory is empty, an empty archive is created. This method overload does not include the base directory in the archive and does not allow you to specify a compression level. If you want to include the base directory or specify a compression level, call the method overload. + /// 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. + /// 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. + /// + /// ]]> /// or is , contains only white space, or contains at least one invalid character. /// or is . /// In or , the specified path, file name, or both exceed the system-defined maximum length. @@ -189,15 +187,14 @@ public static void CreateFromDirectory(string sourceDirectoryName, string destin /// The path of the archive to be created, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. /// One of the enumeration values that indicates whether to emphasize speed or compression effectiveness when creating the entry. /// to include the directory name from at the root of the archive; to include only the contents of the directory. - /// 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. + /// The directory structure from the file system is preserved in the archive. If the directory is empty, an empty archive is created. Use this method overload to specify the compression level and whether to include the base directory in the archive. + /// 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. + /// 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. + /// + /// ]]> /// or is , contains only white space, or contains at least one invalid character. /// or is . /// In or , the specified path, file name, or both exceed the system-defined maximum length. diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs index d7597b16f2b8d7..b00684d20e462d 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs @@ -12,18 +12,18 @@ namespace System.IO.Compression /// + /// How to: Add or Remove References By Using the Reference Manager public static partial class ZipFile { /// Extracts all the files in the specified zip archive to a directory on the file system. /// The path to the archive that is to be extracted. /// The path to the directory in which to place the extracted files, specified as a relative or absolute path. A relative path is interpreted as relative to the current working directory. - /// 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. + /// This method creates the specified directory and all subdirectories. The destination directory cannot already exist. Exceptions related to validating the paths in the or 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 as its source entry has to the root of the archive. + /// 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. + /// + /// ]]> /// or is , contains only white space, or contains at least one invalid character. /// or is . /// The specified path in or exceeds the system-defined maximum length. diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs index ed2e9c24c7d7fc..8410aea2df3987 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs @@ -17,14 +17,13 @@ public static partial class ZipFileExtensions /// The path to the file to be archived. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. /// The name of the entry to create in the zip archive. /// A wrapper for the new entry in the zip archive. - /// property of the entry is set to the last time the file on the file system was changed. - /// When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. - /// ## Examples - /// The following example shows how to create a new entry in a zip archive from an existing file. + /// The new entry in the archive contains the contents of the file specified by . If an entry with the specified name () already exists in the archive, a second entry is created with an identical name. The property of the entry is set to the last time the file on the file system was changed. + /// When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. + /// The following example shows how to create a new entry in a zip archive from an existing file. + /// + /// ]]> /// is , contains only white space, or contains at least one invalid character. /// -or- /// is . @@ -49,14 +48,13 @@ public static ZipArchiveEntry CreateEntryFromFile(this ZipArchive destination, s /// The name of the entry to create in the zip archive. /// One of the enumeration values that indicates whether to emphasize speed or compression effectiveness when creating the entry. /// A wrapper for the new entry in the zip archive. - /// property of the entry is set to the last time the file on the file system was changed. - /// When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. - /// ## Examples - /// The following example shows how to create a new entry in a zip archive from an existing file, and specify the compression level. + /// The new entry in the archive contains the contents of the file specified by . If an entry with the specified name () already exists in the archive, a second entry is created with an identical name. The property of the entry is set to the last time the file on the file system was changed. + /// When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. + /// The following example shows how to create a new entry in a zip archive from an existing file, and specify the compression level. + /// + /// ]]> /// is , contains only white space, or contains at least one invalid character. /// -or- /// is . diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs index 7d1e7080d04b3a..f1f95eb3d70239 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Extract.cs @@ -14,13 +14,12 @@ public static partial class ZipFileExtensions /// Extracts all the files in the zip archive to a directory on the file system. /// The zip archive to extract files from. /// The path to the directory to place the extracted files in. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. - /// exception. The method also creates subdirectories that reflect the hierarchy in the zip archive. 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 - /// The following example shows how to create a new entry in a zip archive from an existing file, and extract the archive to a new directory. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. + /// This method creates the directory specified by . If the destination directory already exists, this method does not overwrite it; it throws an exception. The method also creates subdirectories that reflect the hierarchy in the zip archive. If an error occurs during extraction, the archive remains partially extracted. Each extracted file has the same relative path to the directory specified by as its source entry has to the root of the archive. + /// The following example shows how to create a new entry in a zip archive from an existing file, and extract the archive to a new directory. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. + /// + /// ]]> /// is , contains only white space, or contains at least one invalid character. /// is . /// The specified path exceeds the system-defined maximum length. diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs index 0fc7aafee2f35d..17f4bdb5225420 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs @@ -14,15 +14,14 @@ public static partial class ZipFileExtensions /// Extracts an entry in the zip archive to a file. /// The zip archive entry to extract a file from. /// The path of the file to create from the contents of the entry. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. - /// exception. To overwrite an existing file, use the method overload instead. - /// The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. - /// You cannot use this method to extract a directory; use the method instead. - /// ## Examples - /// The following example shows how to iterate through the contents of a zip archive file and extract files that have a .txt extension. + /// If the destination file already exists, this method does not overwrite it; it throws an exception. To overwrite an existing file, use the method overload instead. + /// The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. + /// You cannot use this method to extract a directory; use the method instead. + /// The following example shows how to iterate through the contents of a zip archive file and extract files that have a .txt extension. + /// + /// ]]> /// is a zero-length string, contains only white space, or contains one or more invalid characters as defined by . /// -or- /// specifies a directory. @@ -51,14 +50,13 @@ public static void ExtractToFile(this ZipArchiveEntry source, string destination /// The zip archive entry to extract a file from. /// The path of the file to create from the contents of the entry. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. /// to overwrite an existing file that has the same name as the destination file; otherwise, . - /// property. - /// You cannot use this method to extract a directory; use the method instead. - /// ## Examples - /// The following example shows how to iterate through the contents of a zip archive file, and extract files that have a .txt extension. It overwrites an existing file that has the same name in the destination folder. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. + /// The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. + /// You cannot use this method to extract a directory; use the method instead. + /// The following example shows how to iterate through the contents of a zip archive file, and extract files that have a .txt extension. It overwrites an existing file that has the same name in the destination folder. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. + /// + /// ]]> /// is a zero-length string, contains only white space, or contains one or more invalid characters as defined by . /// -or- /// specifies a directory. From 443ed57a93e7d2e2599271bfe32b9c9b1593009f Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 00:21:33 -0800 Subject: [PATCH 7/8] Address suggestions. --- .../src/System/IO/Compression/ZipFile.Create.cs | 1 - .../src/System/IO/Compression/ZipFile.Extract.cs | 1 - .../IO/Compression/ZipFileExtensions.ZipArchive.Create.cs | 7 +++++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs index d90adcbff652ea..eed1a1005e1dc6 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Create.cs @@ -12,7 +12,6 @@ namespace System.IO.Compression /// - /// How to: Add or Remove References By Using the Reference Manager public static partial class ZipFile { /// Opens a zip archive for reading at the specified path. diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs index b00684d20e462d..b27e4e42ecaa1b 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFile.Extract.cs @@ -12,7 +12,6 @@ namespace System.IO.Compression /// - /// How to: Add or Remove References By Using the Reference Manager public static partial class ZipFile { /// Extracts all the files in the specified zip archive to a directory on the file system. diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs index 8410aea2df3987..c2b96fe47e669f 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchive.Create.cs @@ -17,8 +17,11 @@ public static partial class ZipFileExtensions /// The path to the file to be archived. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. /// The name of the entry to create in the zip archive. /// A wrapper for the new entry in the zip archive. - /// The new entry in the archive contains the contents of the file specified by . If an entry with the specified name () already exists in the archive, a second entry is created with an identical name. The property of the entry is set to the last time the file on the file system was changed. - /// When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. + /// The new entry in the archive contains the contents of the file specified by . If an entry with the specified name () already exists in the archive, a second entry is created with an identical name. + /// The property of the entry is set to the last time the file on the file system was changed. + /// If the specified source file has an invalid last modified time, the first datetime representable in the Zip timestamp format (midnight on January 1, 1980) will be used. + /// Since no is specified, the default provided by the implementation of the underlying compression algorithm will be used; the will not impose its own default. Currently, the underlying compression algorithm is provided by the class. + /// When is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an . /// The following example shows how to create a new entry in a zip archive from an existing file. /// Date: Thu, 25 Feb 2021 12:17:41 -0800 Subject: [PATCH 8/8] Fix ambiguous method overload. --- .../IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs index 17f4bdb5225420..fe99fdbc06b28e 100644 --- a/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs +++ b/src/libraries/System.IO.Compression.ZipFile/src/System/IO/Compression/ZipFileExtensions.ZipArchiveEntry.Extract.cs @@ -51,7 +51,7 @@ public static void ExtractToFile(this ZipArchiveEntry source, string destination /// The path of the file to create from the contents of the entry. You can specify either a relative or an absolute path. A relative path is interpreted as relative to the current working directory. /// to overwrite an existing file that has the same name as the destination file; otherwise, . /// The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. - /// You cannot use this method to extract a directory; use the method instead. + /// You cannot use this method to extract a directory; use the method instead. /// The following example shows how to iterate through the contents of a zip archive file, and extract files that have a .txt extension. It overwrites an existing file that has the same name in the destination folder. In order to compiler this code example, you must reference the `System.IO.Compression` and `System.IO.Compression.FileSystem` assemblies in your project. ///