Fix note about ? wildcard in EnumerateFiles() (dotnet#7612)

gewarren · web-flow · commit 7c48fbb3c729 · 2023-07-20T16:26:01.000Z
diff --git a/includes/enumerate-files-net-framework.md b/includes/enumerate-files-net-framework.md
@@ -1,9 +1,8 @@
 > [!NOTE]
-> **.NET Framework only:** When you use the asterisk wildcard character in `searchPattern` and you specify a three-character file extension, for example, "\*.txt", this method also returns files with extensions that *begin* with the specified extension. For example, the search pattern "\*.xls" returns both "book.xls" and "book.xlsx". This behavior only occurs if an asterisk is used in the search pattern and the file extension provided is exactly three characters. If you use the question mark wildcard character instead of the asterisk, this method returns only files that match the specified file extension exactly. The following table depicts this anomaly in .NET Framework.
+> **.NET Framework only:** When you use the asterisk wildcard character in `searchPattern` and you specify a three-character file extension, for example, "\*.txt", this method also returns files with extensions that *begin* with the specified extension. For example, the search pattern "\*.xls" returns both "book.xls" and "book.xlsx". This behavior only occurs if an asterisk is used in the search pattern and the file extension provided is exactly three characters. If you use the question mark wildcard character somewhere in the search pattern, this method returns only files that match the specified file extension exactly. The following table depicts this anomaly in .NET Framework.
 >
-> | Files in directory  | Search pattern | .NET 5+ returns   | .NET Framework returns  |
-> |---------------------|----------------|-------------------|-------------------------|
-> | file.ai, file.aif   | *.ai           | file.ai           | file.ai                 |
-> | book.xls, book.xlsx | *.xls          | book.xls          | **book.xls, book.xlsx** |
-> | file.ai, file.aif   | ?.ai           | file.ai           | file.ai                 |
-> | book.xls, book.xlsx | ?.xls          | book.xls          | book.xls                |
+> | Files in directory              | Search pattern | .NET 5+ returns     | .NET Framework returns  |
+> |---------------------------------|----------------|---------------------|-------------------------|
+> | file.ai, file.aif               | *.ai           | file.ai             | file.ai                 |
+> | book.xls, book.xlsx             | *.xls          | book.xls            | **book.xls, book.xlsx** |
+> | ello.txt, hello.txt, hello.txtt | ?ello.txt      | ello.txt, hello.txt | ello.txt, hello.txt     |
diff --git a/xml/System.IO/Directory.xml b/xml/System.IO/Directory.xml
@@ -1246,7 +1246,7 @@ An I/O error occurred.</exception>
   
  The <xref:System.IO.Directory.EnumerateFiles%2A> and <xref:System.IO.Directory.GetFiles%2A> methods differ as follows: When you use <xref:System.IO.Directory.EnumerateFiles%2A>, you can start enumerating the collection of names before the whole collection is returned; when you use <xref:System.IO.Directory.GetFiles%2A>, you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, <xref:System.IO.Directory.EnumerateFiles%2A> can be more efficient.  
   
- The returned collection is not cached; each call to the <xref:System.Collections.Generic.IEnumerable%601.GetEnumerator%2A> on the collection will start a new enumeration.
+The returned collection is not cached. Each call to the <xref:System.Collections.Generic.IEnumerable%601.GetEnumerator%2A> on the collection starts a new enumeration.
   
 ## Examples  
  The following example shows how to retrieve all the text files in a directory and move them to a new directory. After the files are moved, they no longer exist in the original directory.  
@@ -1346,7 +1346,7 @@ An I/O error occurred.</exception>
 
  The <xref:System.IO.Directory.EnumerateFiles%2A> and <xref:System.IO.Directory.GetFiles%2A> methods differ as follows: When you use <xref:System.IO.Directory.EnumerateFiles%2A>, you can start enumerating the collection of names before the whole collection is returned. When you use <xref:System.IO.Directory.GetFiles%2A>, you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, <xref:System.IO.Directory.EnumerateFiles%2A> can be more efficient.
 
- The returned collection is not cached; each call to the <xref:System.Collections.Generic.IEnumerable%601.GetEnumerator%2A> on the collection will start a new enumeration.
+The returned collection is not cached. Each call to the <xref:System.Collections.Generic.IEnumerable%601.GetEnumerator%2A> on the collection starts a new enumeration.
   
  ]]></format>
         </remarks>
@@ -1440,7 +1440,7 @@ An I/O error occurred.</exception>
   
  The <xref:System.IO.Directory.EnumerateFiles%2A> and <xref:System.IO.Directory.GetFiles%2A> methods differ as follows: When you use <xref:System.IO.Directory.EnumerateFiles%2A>, you can start enumerating the collection of names before the whole collection is returned. When you use <xref:System.IO.Directory.GetFiles%2A>, you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, <xref:System.IO.Directory.EnumerateFiles%2A> can be more efficient.  
   
- The returned collection is not cached; each call to the <xref:System.Collections.Generic.IEnumerable%601.GetEnumerator%2A> on the collection will start a new enumeration.
+The returned collection is not cached. Each call to the <xref:System.Collections.Generic.IEnumerable%601.GetEnumerator%2A> on the collection starts a new enumeration.
   
 ## Examples  
  The following example shows how to retrieve all the text files in a directory and its subdirectories, and move them to a new directory. After the files are moved, they no longer exist in the original directories.  
@@ -1449,7 +1449,7 @@ An I/O error occurred.</exception>
  :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/Overview/class5.fs" id="Snippet13":::
  :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Directory/VB/class5.vb" id="Snippet13":::  
   
- The following example recursively enumerates all files that have a .txt extension, reads each line of the file, and displays the line if it contains the string "Microsoft".  
+ The following example recursively enumerates all files that have the extension `.txt`, reads each line of the file, and displays the line if it contains the string "Microsoft".  
   
  :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/EnumerateFiles/program.cs" id="Snippet1":::
  :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/EnumerateFiles/program.fs" id="Snippet1":::
@@ -2896,9 +2896,7 @@ An I/O error occurred.</exception>
   
  The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems.  
   
- For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).  
-  
-   
+ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).
   
 ## Examples  
  The following example demonstrates how to use the <xref:System.IO.Directory.GetFiles%2A> method to return file names from a user-specified location. The example is configured to catch all errors common to this method.  
@@ -2991,27 +2989,19 @@ An I/O error occurred.</exception>
  Characters other than the wildcard are literal characters. For example, the `searchPattern` string "\*t" searches for all names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s".  
   
  `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by <xref:System.IO.Path.DirectorySeparatorChar> or <xref:System.IO.Path.AltDirectorySeparatorChar>, nor can it contain any invalid characters. You can query for invalid characters by using the <xref:System.IO.Path.GetInvalidPathChars%2A> method.  
+
+[!INCLUDE[enumerate-files-net-framework](~/includes/enumerate-files-net-framework.md)]
   
 > [!NOTE]
->  When you use the asterisk wildcard character in a `searchPattern` such as "\*.txt", the number of characters in the specified extension affects the search as follows:  
->   
-> -   If the specified extension is exactly three characters long, the method returns files with extensions that begin with the specified extension. For example, "\*.xls" returns both "book.xls" and "book.xlsx".  
-> -   In all other cases, the method returns files that exactly match the specified extension. For example, "\*.ai" returns "file.ai" but not "file.aif".  
->   
->  When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file\*.txt" returns both files.  
-  
-> [!NOTE]
->  Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT".  
+> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT".  
   
  The <xref:System.IO.Directory.EnumerateFiles%2A> and <xref:System.IO.Directory.GetFiles%2A> methods differ as follows: When you use <xref:System.IO.Directory.EnumerateFiles%2A>, you can start enumerating the collection of names before the whole collection is returned; when you use <xref:System.IO.Directory.GetFiles%2A>, you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, <xref:System.IO.Directory.EnumerateFiles%2A> can be more efficient.  
   
  The `path` parameter can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see <xref:System.IO.Directory.GetCurrentDirectory%2A>.  
   
  The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems.  
   
- For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).  
-  
-   
+ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).
   
 ## Examples  
  The following example counts the number of files that begin with the specified letter.  
@@ -3103,16 +3093,10 @@ An I/O error occurred.</exception>
 
  `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by <xref:System.IO.Path.DirectorySeparatorChar> or <xref:System.IO.Path.AltDirectorySeparatorChar>, nor can it contain any invalid characters. You can query for invalid characters by using the <xref:System.IO.Path.GetInvalidPathChars%2A> method.
 
-> [!NOTE]
->  When you use the asterisk wildcard character in a `searchPattern` such as "\*.txt", the number of characters in the specified extension affects the search as follows:
-> 
-> -   If the specified extension is exactly three characters long, the method returns files with extensions that begin with the specified extension. For example, "\*.xls" returns both "book.xls" and "book.xlsx".
-> -   In all other cases, the method returns files that exactly match the specified extension. For example, "\*.ai" returns "file.ai" but not "file.aif".
-> 
->  When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file\*.txt" returns both files.
+[!INCLUDE[enumerate-files-net-framework](~/includes/enumerate-files-net-framework.md)]
 
 > [!NOTE]
->  Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT".
+> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT".
 
  The <xref:System.IO.Directory.EnumerateFiles%2A> and <xref:System.IO.Directory.GetFiles%2A> methods differ as follows: When you use <xref:System.IO.Directory.EnumerateFiles%2A>, you can start enumerating the collection of names before the whole collection is returned; when you use <xref:System.IO.Directory.GetFiles%2A>, you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, <xref:System.IO.Directory.EnumerateFiles%2A> can be more efficient.
 
@@ -3206,18 +3190,12 @@ An I/O error occurred.</exception>
   
  Characters other than the wildcard are literal characters. For example, the `searchPattern` string "\*t" searches for all names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s".  
   
- `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by <xref:System.IO.Path.DirectorySeparatorChar> or <xref:System.IO.Path.AltDirectorySeparatorChar>, nor can it contain any invalid characters. You can query for invalid characters by using the <xref:System.IO.Path.GetInvalidPathChars%2A> method.  
-  
-> [!NOTE]
->  When you use the asterisk wildcard character in a `searchPattern` such as "\*.txt", the number of characters in the specified extension affects the search as follows:  
->   
-> -   If the specified extension is exactly three characters long, the method returns files with extensions that begin with the specified extension. For example, "\*.xls" returns both "book.xls" and "book.xlsx".  
-> -   In all other cases, the method returns files that exactly match the specified extension. For example, "\*.ai" returns "file.ai" but not "file.aif".  
->   
->  When you use the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files, "file1.txt" and "file1.txtother", in a directory, a search pattern of "file?.txt" returns just the first file, whereas a search pattern of "file*.txt" returns both files.  
-  
+ `searchPattern` cannot end in two periods ("..") or contain two periods ("..") followed by <xref:System.IO.Path.DirectorySeparatorChar> or <xref:System.IO.Path.AltDirectorySeparatorChar>, nor can it contain any invalid characters. You can query for invalid characters by using the <xref:System.IO.Path.GetInvalidPathChars%2A> method.
+
+[!INCLUDE[enumerate-files-net-framework](~/includes/enumerate-files-net-framework.md)]
+
 > [!NOTE]
->  Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT".  
+> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "\*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" returns "longfilename.txt" because the equivalent 8.3 file name format is "LONGFI~1.TXT".  
   
  The <xref:System.IO.Directory.EnumerateFiles%2A> and <xref:System.IO.Directory.GetFiles%2A> methods differ as follows: When you use <xref:System.IO.Directory.EnumerateFiles%2A>, you can start enumerating the collection of names before the whole collection is returned; when you use <xref:System.IO.Directory.GetFiles%2A>, you must wait for the whole array of names to be returned before you can access the array. Therefore, when you are working with many files and directories, <xref:System.IO.Directory.EnumerateFiles%2A> can be more efficient.  
   
