ComponentPro UltimateFtp

      Wildcard masks and search criterion

      Language Filter: AllSend comments on this topic to ComponentPro

      File masks

      Ultimate FTP allows using file masks as parameter for multi-file operations such as upload, download, delete, move, and set permissions. File masks consist of three types of symbols and their combinations:

      • Fixed characters: Any letter, number or character that is allowed in a file name. For example, pic.jpg refers to a single file named as ‘pic.jpg’.
      • Question Mark (?): A question mark (?) denotes any single character. For example, ?in.docx can refer to every file with a name consisting of three letters ending with ‘in’ and .docx as an extension like tin.docx, kin.docx, fin.docx, etc.
      • Asterisk (*): An asterisk refers to various characters of an indefinite number. For example, a*t.docx can refer to all .docx files with a name starting with ‘a’ and ending with ‘t’ and can contain any number of characters in between like at.docx, ant.docx, aunt.docx, etc.
      '**' is the special wildcard that is used to match any character, including directory separators. See this for more details.

      The above examples show that a file mask with only fixed characters refers to a single unique file (e.g. file mask my-picture.jpg refers to, and only to, a file named my-picture.jpg), while file masks containing wildcards such as ‘?’ or/and ‘*’ can refer to both single or multiple files.

      File mask and wildcard usage examples:

      File masks Description and Examples
      * All files with any extension.
      *.* All files with any extension.

      Files with extension .png.

      • hill.png
      • wallpaper.png
      • 2.png

      Files with extension starting with d.

      • document.doc
      • document.docx
      • live.dat
      • 2.d

      Files starting with peo.

      • people.jpg
      • people-flash.ico
      • peo-123.htm
      • peo

      .html files starting with anything and ending with mat followed by any single character.

      • automate.html
      • tomato.html
      • mate.html

      .xls files starting with doc and followed by any five characters.

      • document.xls
      • doc-2017.xls
      • docfiles.xls

      Files with three characters in their name and two characters in extension.

      • job.cs
      • 123.48

      Files with four characters in their name and without extension.

      • task
      • good
      • like

      The following example demonstrates how to use file masks in multi-file operations:

      using ComponentPro.Net;
      // Create a new class instance.
      Ftp client = new Ftp();
      // Connect to the FTP server.
      // Authenticate.
      client.Authenticate("userName", "password");
      // ... 
      // Rename remote file '/file.dat' to 'myfile.dat'
      client.Rename("/file.dat", "/myfile.dat");
      // Move a file
      client.Rename("/file2.dat", "/new-folder/file2.dat");
      // Rename a remote directory
      client.Rename("/album-folder", "/old-album-folder");
      // Move a directory
      client.Rename("/album-folder2", "/new-folder/album-folder2");
      // ... 
      // Disconnect.
      For transferring file with advanced filters, see this "Upload/download files with advanced filters" topic.

      Search condition

      File masks are useful to filter item name only. What if you want to filter items by file size or combine several file masks together? That is when the SearchCondition class should be used. The SearchCondition provides the following powerful filtering features:

      Filter by path masks - "**" wildcard mask

      "**" is the special wildcard to match any character, including directory separators. For example:

      • /data/**/file.dat matches /data/file.dat, /data/a/file.dat, and /data/a/b/file.dat

      Fluent API

      SearchCondition filters =
          // All .TXT and .DAT files 
          // with size > 100kb 
          + new SizeSearchCondition(100 * 1024, long.MaxValue)
          // in important directories under '/data' only 
          + new NameSearchCondition("/data/**/important", SearchConditionFileTypes.Directory)
          // Exclude all files in "Temp" directories 
          - new NameSearchCondition("Temp", SearchConditionFileTypes.Directory)
      // Upload files in D:\data to /data.
      client.Upload(@"D:\data", "/data", filters);

      Filter by file masks - NameSearchCondition

      // Upload files starting with 'best'.
      client.Upload(@"C:\Test", "/", new NameSearchCondition("best*"));

      Filter by regex - NameRegexSearchCondition

      // Use regex pattern.
      client.Upload(@"C:\Test", "/", new NameRegexSearchCondition(@"\d\sFile\.exe"));

      Filter by file size - SizeSearchCondition

      // Upload files larger than or equal to 1M and less than or equal to 2M.
      client.Upload(@"C:\Test", "/", new SizeSearchCondition(1 * 1024 * 1024, 2 * 1024 * 1024));

      Filter by item last write time - TimeSearchCondition

      // Upload files created since yesterday.
      client.Upload(@"C:\Test", "/", new TimeSearchCondition(DateTime.Now.AddDays(-1), DateTime.MaxValue));

      Filter by item attributes - AttributeSearchCondition

      // Upload files with .exe extension and are not hidden.
      client.Upload(@"C:\temp", "/", new NameSearchCondition("*.exe") - new AttributeSearchCondition(FileAttributes.Hidden));

      Support logical AND operation - AndSearchCondition

      // Download '.exe' file and size greater than 200kb. 
      // The '+' operator can also be used to combine two SearchCondition objects
      client.Download("/", @"C:\temp", new NameSearchCondition("*.exe") + new SizeSearchCondition(200 * 1024, long.MaxValue));
      // Upload files starting with 'test' or ending with '.cs' or '.vb' and also larger than or equal to 1M
      client.Upload(@"C:\Test", "/", new AndSearchCondition(new NameSearchCondition("test*") | new NameSearchCondition("*.cs;*.vb"),
                                      new SizeSearchCondition(1024 * 1024, long.MaxValue))

      Support logical OR operation - OrSearchCondition

      // Upload files starting with 'best' or ending with '.cs' or '.vb'.
      client.Upload(@"C:\Test", "/", new NameSearchCondition("best*") | new NameSearchCondition("*.cs;*.vb"));
      // Upload files starting with 'test' or ending with '.cs' or '.vb' and also larger than or equal to 1M
      client.Upload(@"C:\Test", "/", new AndSearchCondition(new NameSearchCondition("test*") | new NameSearchCondition("*.cs;*.vb"),
                                      new SizeSearchCondition(1024 * 1024, long.MaxValue))

      Support logical NOT operation - NotSearchCondition

      // Download all files that are not hidden. 
      // The '!' (not) operator can also be used to reverse a condition
      client.Upload(@"C:\temp", "/", !new AttributeSearchCondition(FileAttributes.Hidden));
      // Upload files not starting with 'test' nor 'real'
      client.Upload(@"C:\Test", "/", new NotSearchCondition(new OrSearchCondition(
                                              new NameSearchCondition("test*"), 
                                              new NameSearchCondition("real*")))

      Write a custom search condition

      You can write a custom search condition that inherit from the SearchCondition class

      class CustomSearchCondition : SearchCondition
          /// <summary> 
          /// Initializes a new instance of the <see cref="SearchCondition"/> class. 
          /// </summary> 
          /// <param name="fileTypes">The file types to search.</param> 
          protected CustomSearchCondition(SearchConditionFileTypes fileTypes)
              : base(fileTypes)
          /// <summary> 
          /// Returns a boolean value indicating whether the item matches the search condition. 
          /// </summary> 
          /// <param name="file">The <see cref="FileInfoBase"/> to check.</param> 
          /// <exception cref="ArgumentNullException"><paramref name="file"/> is a null reference (Nothing in VB.NET).</exception> 
          public override bool Matches(FileInfoBase file)
              if (file == null)
                  throw new ArgumentNullException("file");
              // Return true if file size is even - a file is matched if its size is even. 
              return file.Length % 2 == 0;