en-US/about_whiskey_Zip_Task.help.txt
|
TOPIC
about_Whiskey_Zip_Task SUMMARY Creates ZIP archives. DESCRIPTION The `Zip` task creates ZIP archives. You must set the path to the output file with the `ArchivePath` property. The archive's directory will be created if it doesn't exist. Any existing file will be deleted and a new ZIP archive created in its place. You must also set the paths of any files or directories to include in the archive with the `Path` property. It should be a list of paths, relative to your whiskey.yml file, of files/directories to include in your archive. Items will be added to the archive using their path relative to the whiskey.yml file. You can change this path in two ways. First, for each item, you can change its name using YAML's key/value syntax, e.g. Build: - Zip: ArchivePath: $(WHISKEY_OUTPUT_DIRECTORY)\Whiskey.zip Path: - Whiskey - LICENSE: Whiskey\LICENSE - NOTICE: Whiskey\NOTICE In this example, the LICENSE file's path in the ZIP file is changed from `LICENSE` to `Whiskey\LICENSE` (the same thing happens with the `NOTICE` file). The other way to change the location of items in the archive is with the `SourceRoot` property. This property controls what the task considers the root directory for resolving paths. Normally, paths are resolved relative to the build root (the same directory as the whiskey.yml file). If present, `SourceRoot` changes paths to be relative to the `SourceRoot` path. Item paths in the archive would be relative to the source root. You can use the `Include` property to filter directories. If present, all directories in the `Path` property will only include items that match an item in the `Include` property. Wildcards are supported. You can use the `Exclude` property to filter directories. If present, all directories in the `Path` property will not include items that match an item in the `Exclude` property. Wildcards are supported. PROPERTIES * `ArchivePath` (mandatory): the path to the ZIP archive to create. An existing file will be deleted. The archive's parent directories will be created if they don't exist. * `Path` (mandatory): the directories and filenames to include in the archive. Each path must be relative to the whiskey.yml file. You can change the root path the task uses to resolve these paths with the `SourceRoot` property. Each item is added to the archive at the same relative path as its source item (relative to the build root, or the source root, if the `SourceRoot` property is present). If you have two paths with the same name, the second item will replace the first. You can customize the path of the item in the archive by converting the value into a key/value pair, e.g. `source_dir\source_file.ps1`: `destination_dir\destination_file.ps1`. * `Include`: a list of wildcards and file names to include in the archive. This filters is applied to directories in the `Path` property. Only files whose names match a wildcard in this list will be included. By default, all items in a directory are included. * `Exclude`: a list of wildcards, file names, and directory names to exclude from the archive. This filters applies to directories in the `Path` property. Only files/directories whose names do not match an item in this list will be included. * `SourceRoot`: this changes the root path used to resolve the relative paths in the `Path` property. Also, items will be added to the archive with a path relative to this directory. Use this element when your application's root directory isn't the same directory your whiskey.yml file is in. This path should be relative to the whiskey.yml file. * `CompressionLevel`: the compression level to use when creating the archive. The default is `Optimal`. Valid values are `Optimal` (smaller archive but created slower), `Fastest` (larger archive but created faster), and `NoCompression` (largest file, created fastest, no compression). * `EntryNameEncoding`: by default, entry names in the ZIP archive are encoded with UTF-8. If the archive will be consumed by a tool that doesn't handle UTF-8, change the encoding of entries with this property. You may specify an encoding name or code page ID. For a list of built-in encodings, see https://docs.microsoft.com/en-us/dotnet/api/system.text.encoding. You can also run `[Text.Encoding]::GetEncodings()`. EXAMPLES ## Example 1 Build: - Zip: ArchivePath: $(WHISKEY_OUTPUT_DIRECTORY)\Whiskey.zip Path: - Whiskey Demonstrates the minimal configuration needed to create a ZIP file. In this case, a Whiskey.zip file will be created in the build output directory. This archive will contain a "Whiskey" directory, which will contain the contents of the "Whiskey" directory. ## Example 2 Build: - Zip: ArchivePath: $(WHISKEY_OUTPUT_DIRECTORY)\Whiskey.zip Path: - Whiskey Include: - "*.ps1" Demonstrates how to filter any directories in the "Path" property. In this example, the archive will only contain all "*.ps1" files under the "Whiskey" directory. ## Example 3 Build: - Zip: ArchivePath: $(WHISKEY_OUTPUT_DIRECTORY)\Whiskey.zip Path: - Whiskey Exclude: - "*.xml" - "*.pdb" - "*.orig" Demonstrates how to exclude files/directories from any directories in the "Path" property. In this example, no "*.xml", "*.pdb", or "*.orig" files under the "Whiskey" directory will be included in the archive. ## Example 4 Build: - Zip: ArchivePath: $(WHISKEY_OUTPUT_DIRECTORY)\Whiskey.zip Path: - Whiskey - LICENSE - NOTICE - LICENSE: Whiskey\LICENSE - NOTICE: Whiskey\NOTICE Demonstrates how to customize the name/path of an item in the archive. In this case, the LICENSE and NOTICE files will be in both the root of the archive and in the "Whiskey" directory in the archive. |