Class FileSelector
FileSelector encapsulates logic that selects files from a source - a zip file or the filesystem - based on a set of criteria. This class is used internally by the DotNetZip library, in particular for the AddSelectedFiles() methods. This class can also be used independently of the zip capability in DotNetZip.
public class FileSelector- Inheritance
-
FileSelector
- Inherited Members
- Extension Methods
Remarks
The FileSelector class is used internally by the ZipFile class for selecting files for inclusion into the ZipFile, when the AddSelectedFiles(string, string) method, or one of its overloads, is called. It's also used for the ExtractSelectedEntries(string) methods. Typically, an application that creates or manipulates Zip archives will not directly interact with the FileSelector class.
Some applications may wish to use the FileSelector class directly, to select files from disk volumes based on a set of criteria, without creating or querying Zip archives. The file selection criteria include: a pattern to match the filename; the last modified, created, or last accessed time of the file; the size of the file; and the attributes of the file.
Consult the documentation for SelectionCriteria for more information on specifying the selection criteria.
Constructors
FileSelector(string)
Constructor that allows the caller to specify file selection criteria.
public FileSelector(string selectionCriteria)Parameters
selectionCriteriastringThe criteria for file selection.
Remarks
This constructor allows the caller to specify a set of criteria for selection of files.
See SelectionCriteria for a description of the syntax of the selectionCriteria string.
By default the FileSelector will traverse NTFS Reparse Points. To change this, use FileSelector(String, bool).
FileSelector(string, bool)
Constructor that allows the caller to specify file selection criteria.
public FileSelector(string selectionCriteria, bool traverseDirectoryReparsePoints)Parameters
selectionCriteriastringThe criteria for file selection.
traverseDirectoryReparsePointsboolwhether to traverse NTFS reparse points (junctions).
Remarks
This constructor allows the caller to specify a set of criteria for selection of files.
See SelectionCriteria for a description of the syntax of the selectionCriteria string.
Properties
SelectionCriteria
The string specifying which files to include when retrieving.
public string SelectionCriteria { get; set; }Property Value
Remarks
Specify the criteria in statements of 3 elements: a noun, an operator, and a value. Consider the string "name != *.doc" . The noun is "name". The operator is "!=", implying "Not Equal". The value is "*.doc". That criterion, in English, says "all files with a name that does not end in the .doc extension."
Supported nouns include "name" (or "filename") for the filename; "atime", "mtime", and "ctime" for last access time, last modfied time, and created time of the file, respectively; "attributes" (or "attrs") for the file attributes; "size" (or "length") for the file length (uncompressed); and "type" for the type of object, either a file or a directory. The "attributes", "type", and "name" nouns all support = and != as operators. The "size", "atime", "mtime", and "ctime" nouns support = and !=, and >, >=, <, <= as well. The times are taken to be expressed in local time.
Specify values for the file attributes as a string with one or more of the characters H,R,text,A,I,L in any order, implying file attributes of Hidden, ReadOnly, System, Archive, NotContextIndexed, and ReparsePoint (symbolic link) respectively.
To specify a time, use YYYY-MM-DD-HH:mm:ss or YYYY/MM/DD-HH:mm:ss as the format. If you omit the HH:mm:ss portion, it is assumed to be 00:00:00 (midnight).
The value for a size criterion is expressed in integer quantities of bytes, kilobytes (use k or kb after the number), megabytes (m or mb), or gigabytes (g or gb).
The value for a name is a pattern to match against the filename, potentially including wildcards. The pattern follows CMD.exe glob rules: * implies one or more of any character, while ? implies one character. If the name pattern contains any slashes, it is matched to the entire filename, including the path; otherwise, it is matched against only the filename without the path. This means a pattern of "*\*.*" matches all files one directory level deep, while a pattern of "*.*" matches all files in all directories.
To specify a name pattern that includes spaces, use single quotes around the pattern. A pattern of "'* *.*'" will match all files that have spaces in the filename. The full criteria string for that would be "name = '* *.*'" .
The value for a type criterion is either F (implying a file) or D (implying a directory).
Some examples:
| criteria | Files retrieved |
|---|---|
| name != *.xls | any file with an extension that is not .xls |
| name = *.mp3 | any file with a .mp3 extension. |
| *.mp3 | (same as above) any file with a .mp3 extension. |
| attributes = A | all files whose attributes include the Archive bit. |
| attributes != H | all files whose attributes do not include the Hidden bit. |
| mtime > 2009-01-01 | all files with a last modified time after January 1st, 2009. |
| ctime > 2009/01/01-03:00:00 | all files with a created time after 3am (local time), on January 1st, 2009. |
| size > 2gb | all files whose uncompressed size is greater than 2gb. |
| type = D | all directories in the filesystem. |
You can combine criteria with the conjunctions AND, OR, and XOR. Using a string like "name = *.txt AND size >= 100k" for the selectionCriteria retrieves entries whose names end in .txt, and whose uncompressed size is greater than or equal to 100 kilobytes.
For more complex combinations of criteria, you can use parenthesis to group clauses in the boolean logic. Absent parenthesis, the precedence of the criterion atoms is determined by order of appearance. Unlike the character# language, the AND conjunction does not take precendence over the logical OR. This is important only in strings that contain 3 or more criterion atoms. In other words, "name = *.txt and size > 1000 or attributes = H" implies "((name = *.txt AND size > 1000) OR attributes = H)" while "attributes = H OR name = *.txt and size > 1000" evaluates to "((attributes = H OR name = *.txt) AND size > 1000)". When in doubt, use parenthesis.
Using time properties requires some extra care. If you want to retrieve all entries that were last updated on 2009 February 14, specify "mtime >= 2009-02-14 AND mtime < 2009-02-15". Read this to say: all files updated after 12:00am on February 14th, until 12:00am on February 15th. You can use the same bracketing approach to specify any time period - a year, a month, a week, and so on.
The syntax allows one special case: if you provide a string with no spaces, it is treated as a pattern to match for the filename. Therefore a string like "*.xls" will be equivalent to specifying "name = *.xls". This "shorthand" notation does not work with compound criteria.
There is no logic in this class that insures that the inclusion criteria are internally consistent. For example, it's possible to specify criteria that says the file must have a size of less than 100 bytes, as well as a size that is greater than 1000 bytes. Obviously no file will ever satisfy such criteria, but this class does not check for or detect such inconsistencies.
Exceptions
- Exception
Thrown in the setter if the value has an invalid syntax.
TraverseReparsePoints
Indicates whether searches will traverse NTFS reparse points, like Junctions.
public bool TraverseReparsePoints { get; set; }Property Value
Methods
SelectEntries(ZipFile)
Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria.
public ICollection<ZipEntry> SelectEntries(ZipFile zip)Parameters
zipZipFileThe ZipFile from which to retrieve entries.
Returns
- ICollection<ZipEntry>
a collection of ZipEntry objects that conform to the criteria.
Remarks
This method applies the criteria set in the FileSelector instance (as described in the SelectionCriteria) to the specified ZipFile. Using this method, for example, you can retrieve all entries from the given ZipFile that have filenames ending in .txt.
Normally, applications would not call this method directly. This method is used by the ZipFile class.
Using the appropriate SelectionCriteria, you can retrieve entries based on size, time, and attributes. See SelectionCriteria for a description of the syntax of the SelectionCriteria string.
SelectEntries(ZipFile, string)
Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria.
public ICollection<ZipEntry> SelectEntries(ZipFile zip, string directoryPathInArchive)Parameters
zipZipFileThe ZipFile from which to retrieve entries.
directoryPathInArchivestringthe directory in the archive from which to select entries. If null, then all directories in the archive are used.
Returns
- ICollection<ZipEntry>
a collection of ZipEntry objects that conform to the criteria.
Remarks
This method applies the criteria set in the FileSelector instance (as described in the SelectionCriteria) to the specified ZipFile. Using this method, for example, you can retrieve all entries from the given ZipFile that have filenames ending in .txt.
Normally, applications would not call this method directly. This method is used by the ZipFile class.
This overload allows the selection of ZipEntry instances from the ZipFile to be restricted to entries contained within a particular directory in the ZipFile.
Using the appropriate SelectionCriteria, you can retrieve entries based on size, time, and attributes. See SelectionCriteria for a description of the syntax of the SelectionCriteria string.
SelectFiles(string)
Returns the names of the files in the specified directory that fit the selection criteria specified in the FileSelector.
public ICollection<string> SelectFiles(string directory)Parameters
directorystringThe name of the directory over which to apply the FileSelector criteria.
Returns
- ICollection<string>
A collection of strings containing fully-qualified pathnames of files that match the criteria specified in the FileSelector instance.
Remarks
This is equivalent to calling SelectFiles(string, bool) with recurseDirectories = false.
SelectFiles(string, bool)
Returns the names of the files in the specified directory that fit the selection criteria specified in the FileSelector, optionally recursing through subdirectories.
public ReadOnlyCollection<string> SelectFiles(string directory, bool recurseDirectories)Parameters
directorystringThe name of the directory over which to apply the FileSelector criteria.
recurseDirectoriesboolWhether to recurse through subdirectories when applying the file selection criteria.
Returns
- ReadOnlyCollection<string>
A collection of strings containing fully-qualified pathnames of files that match the criteria specified in the FileSelector instance.
Remarks
This method applies the file selection criteria contained in the FileSelector to the files contained in the given directory, and returns the names of files that conform to the criteria.
ToString()
Returns a string representation of the FileSelector object.
public override string ToString()Returns
- string
The string representation of the boolean logic statement of the file selection criteria for this instance.