Merge pull request dotnet#5399 from dotnet/main

Publish live from main

Author: BillWagner

.github/workflows/version-sweep.yml

@@ -0,0 +1,43 @@
+# This is a basic workflow to help you get started with Actions
+
+name: 'target supported version'
+
+# Controls when the action will run. 
+on:
+ # Triggers the workflow on push or pull request events but only for the master branch
+ schedule:
+ - cron: '0 0 1 * *'
+ workflow_dispatch:
+ inputs:
+ reason:
+ description: 'The reason for running the workflow'
+ required: true
+ default: 'Manual run'
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+ # This workflow contains a single job called "build"
+ version-sweep:
+ # The type of runner that the job will run on
+ runs-on: ubuntu-latest
+
+ # Steps represent a sequence of tasks that will be executed as part of the job
+ steps:
+ # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+ - uses: actions/checkout@v2
+
+ # Runs a single command using the runners shell
+ - name: 'Print manual run reason'
+ if: ${{ github.event_name == 'workflow_dispatch' }}
+ run: |
+ echo 'Reason: ${{ github.event.inputs.reason }}'
+ # Start the .NET version sweeper, scan projects/slns for non-LTS (or currrent) versions
+ - name: .NET version sweeper
+ id: dotnet-version-sweeper
+ uses: dotnet/versionsweeper@v1.2
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ with:
+ owner: ${{ github.repository_owner }}
+ name: ${{ github.repository }}
+ branch: ${{ github.ref }}

xml/Microsoft.Extensions.FileSystemGlobbing/FilePatternMatch.xml

@@ -53,8 +53,8 @@
  <Parameter Name="stem" Type="System.String" />
  </Parameters>
  <Docs>
- <param name="path">The path to the matched file</param>
- <param name="stem">The stem</param>
+ <param name="path">The path to the file matched, relative to the beginning of the matching search pattern.</param>
+ <param name="stem">The subpath to the file matched, relative to the first wildcard in the matching search pattern.</param>
  <summary>Initializes new instance of <see cref="T:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch" /></summary>
  <remarks>To be added.</remarks>
  </Docs>
@@ -180,10 +180,10 @@
  <ReturnType>System.String</ReturnType>
  </ReturnValue>
  <Docs>
- <summary>The path to the file matched.</summary>
+ <summary>The path to the file matched, relative to the beginning of the matching search pattern.</summary>
  <value>To be added.</value>
- <remarks>If the matcher searched for "**/*.cs" using "src/Project" as the directory base and the pattern matcher found
-  "src/Project/Interfaces/IFile.cs", then Stem = "Interfaces/IFile.cs" and Path = "src/Project/Interfaces/IFile.cs".</remarks>
+ <remarks>If the matcher searched for "src/Project/**/*.cs" and the pattern matcher found "src/Project/Interfaces/IFile.cs",
+ then <see cref="Stem" /> = "Interfaces/IFile.cs" and <see cref="Path" /> = "src/Project/Interfaces/IFile.cs".</remarks>
  </Docs>
  </Member>
  <Member MemberName="Stem">
@@ -209,11 +209,10 @@
  <ReturnType>System.String</ReturnType>
  </ReturnValue>
  <Docs>
- <summary>The subpath to the matched file under the base directory searched.</summary>
+ <summary>The subpath to the file matched, relative to the first wildcard in the matching search pattern.</summary>
  <value>To be added.</value>
- <remarks>If the matcher searched for "**/*.cs" using "src/Project" as the directory base and the pattern matcher found
- "src/Project/Interfaces/IFile.cs",
- then Stem = "Interfaces/IFile.cs" and Path = "src/Project/Interfaces/IFile.cs".</remarks>
+ <remarks>If the matcher searched for "src/Project/**/*.cs" and the pattern matcher found "src/Project/Interfaces/IFile.cs",
+ then <see cref="Stem" /> = "Interfaces/IFile.cs" and <see cref="Path" /> = "src/Project/Interfaces/IFile.cs".</remarks>
  </Docs>
  </Member>
  </Members>

xml/System.IO/File.xml

@@ -2518,6 +2518,8 @@ Note that if you attempt to replace a file by moving a file of the same name int
 
 The `sourceFileName` and `destFileName` arguments can include 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>.
 
+Moving the file across disk volumes is equivalent to copying the file and deleting it from the source if the copying was successful.
+
 If you try to move a file across disk volumes and that file is in use, the file is copied to the destination, but it is not deleted from the source.
 
 For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).
@@ -2534,6 +2536,10 @@ The following example moves a file.
  </remarks>
  <exception cref="T:System.IO.IOException">
  <paramref name="destFileName" /> already exists.
+
+ -or-
+
+ An I/O error has occurred, e.g. while copying the file across disk volumes.
  </exception>
  <exception cref="T:System.IO.FileNotFoundException">
  <paramref name="sourceFileName" /> was not found.
@@ -2595,6 +2601,8 @@ This method works across disk volumes, and it does not throw an exception if the
 
 The `sourceFileName` and `destFileName` arguments can include 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>.
 
+Moving the file across disk volumes is equivalent to copying the file and deleting it from the source if the copying was successful.
+
 If you try to move a file across disk volumes and that file is in use, the file is copied to the destination, but it is not deleted from the source.
 
 For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks).
@@ -2611,6 +2619,10 @@ The following example moves a file.
  </remarks>
  <exception cref="T:System.IO.IOException">
  <paramref name="destFileName" /> already exists and <paramref name="overwrite" /> is <see langword="false" />.
+
+ -or-
+
+ An I/O error has occurred, e.g. while copying the file across disk volumes.
  </exception>
  <exception cref="T:System.IO.FileNotFoundException">
  <paramref name="sourceFileName" /> was not found.</exception>

xml/System.IO/Path.xml

@@ -58,7 +58,7 @@
  
 ## Remarks 
  
- A path is a string that provides the location of a file or directory. A path does not necessarily point to a location on disk; for example, a path might map to a location in memory or on a device. The exact format of a path is determined by the current platform. For example, on some systems, a path can start with a drive or volume letter, while this element is not present in other systems. On some systems, file paths can contain extensions, which indicate the type of information stored in the file. The format of a file name extension is platform-dependent; for example, some systems limit extensions to three characters, and others do not. The current platform also determines the set of characters used to separate the elements of a path, and the set of characters that cannot be used when specifying paths. Because of these differences, the fields of the `Path` class as well as the exact behavior of some members of the `Path` class are platform-dependent. 
+ A path is a string that provides the location of a file or directory. A path does not necessarily point to a location on disk; for example, a path might map to a location in memory or on a device. The exact format of a path is determined by the current platform. For example, on some systems, a path can start with a drive or volume letter, while this element is not present in other systems. On some systems, file paths can contain extensions, which indicate the type of information stored in the file. The format of a file name extension is platform-dependent; for example, some systems limit extensions to three characters (such as FAT16 commonly used on smaller flash storage and older versions of ISO 9660 used on optical media), and others do not. The current platform also determines the set of characters used to separate the elements of a path, and the set of characters that cannot be used when specifying paths. Because of these differences, the fields of the `Path` class as well as the exact behavior of some members of the `Path` class are platform-dependent. 
  
  A path can contain absolute or relative location information. Absolute paths fully specify a location: the file or directory can be uniquely identified regardless of the current location. Relative paths specify a partial location: the current location is used as the starting point when locating a file specified with a relative path. To determine the current directory, call <xref:System.IO.Directory.GetCurrentDirectory%2A?displayProperty=nameWithType>. 
 
@@ -1930,7 +1930,7 @@ Paths are resolved by calling the <xref:System.IO.Path.GetFullPath%2A> method be
 
 # [Linux](#tab/linux)
 
-1. The path specified by the TMPDIR environment variable. 
+1. The path specified by the TMPDIR environment variable. If the path is not specified in the `TMPDIR` environment variable, the default path `/tmp/` is used.  
 
 ---
 

xml/System.Net.Http.Headers/TransferCodingWithQualityHeaderValue.xml

@@ -37,7 +37,7 @@
  </Interface>
  </Interfaces>
  <Docs>
- <summary>Represents an Accept-Encoding header value.with optional quality factor.</summary>
+ <summary>Represents an Accept-Encoding header value with optional quality factor.</summary>
  <remarks>
  <format type="text/markdown"><![CDATA[ 
  

xml/System.Net.Http/HttpClient.xml

@@ -117,7 +117,7 @@ Starting with .NET Core 2.1, the <xref:System.Net.Http.SocketsHttpHandler?displa
 - The elimination of platform dependencies, which simplifies deployment and servicing. For example, `libcurl` is no longer a dependency on .NET Core for macOS and .NET Core for Linux.
 - Consistent behavior across all .NET platforms.
 
-If this change is undesirable, on Windows you can still use <xref:System.Net.Http.WinHttpHandler> by referencing it's [NuGet package](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler/) and passing it to [`HttpClient`'s constructor`](xref:System.Net.Http.HttpClient.%23ctor(System.Net.Http.HttpMessageHandler)) manually.
+If this change is undesirable, on Windows you can still use <xref:System.Net.Http.WinHttpHandler> by referencing it's [NuGet package](https://www.nuget.org/packages/System.Net.Http.WinHttpHandler/) and passing it to [`HttpClient`'s constructor](xref:System.Net.Http.HttpClient.%23ctor(System.Net.Http.HttpMessageHandler)) manually.
 
 ### Configure behavior using run-time configuration options
 

xml/System.Net.Http/HttpMessageHandler.xml

@@ -245,7 +245,7 @@
 ## Remarks 
  This operation will not block. The returned <xref:System.Threading.Tasks.Task%601> object will complete once the entire response including content is read. 
  
- The <xref:System.Net.Http.HttpMessageHandler.SendAsync%2A> method is used primarily by the system. This method is called by the system one of the <xref:System.Net.Http.HttpClient.SendAsync%2A?displayProperty=nameWithType> methods is called. Most apps will never call this method. 
+ The <xref:System.Net.Http.HttpMessageHandler.SendAsync%2A> method is used primarily by the system. This method is called by the system when one of the <xref:System.Net.Http.HttpClient.SendAsync%2A?displayProperty=nameWithType> methods is called. Most apps will never call this method. 
  
  ]]></format>
  </remarks>

xml/System.Threading.Tasks/Task.xml

@@ -119,7 +119,7 @@
  
 <a name="WaitingForOne"></a> 
 ## Waiting for one or more tasks to complete 
- Because tasks typically run asynchronously on a thread pool thread, the thread that creates and starts the task continues execution as soon as the task has been instantiated. In some cases, when the calling thread is the main application thread, the app may terminate before any the task actually begins execution. In others,  your application's logic may require that the calling thread continue execution only when one or more tasks has completed execution. You can synchronize the execution of the calling thread and the asynchronous tasks it launches by calling a `Wait` method to wait for one or more tasks to complete. 
+ Because tasks typically run asynchronously on a thread pool thread, the thread that creates and starts the task continues execution as soon as the task has been instantiated. In some cases, when the calling thread is the main application thread, the app may terminate before the task actually begins execution. In others, your application's logic may require that the calling thread continue execution only when one or more tasks have completed execution. You can synchronize the execution of the calling thread and the asynchronous tasks it launches by calling a `Wait` method to wait for one or more tasks to complete. 
  
  To wait for a single task to complete, you can call its <xref:System.Threading.Tasks.Task.Wait%2A?displayProperty=nameWithType> method. A call to the <xref:System.Threading.Tasks.Task.Wait%2A> method blocks the calling thread until the single class instance has completed execution. 
  
@@ -135,7 +135,7 @@
  
  You can also supply a cancellation token by calling the <xref:System.Threading.Tasks.Task.Wait%28System.Threading.CancellationToken%29> and <xref:System.Threading.Tasks.Task.Wait%28System.Int32%2CSystem.Threading.CancellationToken%29> methods. If the token's <xref:System.Threading.CancellationToken.IsCancellationRequested%2A> property is `true` or becomes `true` while the <xref:System.Threading.Tasks.Task.Wait%2A> method is executing, the method throws an <xref:System.OperationCanceledException>. 
  
- In some cases, you may want to wait for the first of a series of executing tasks to complete, but don't care which task it is. For this purpose, you can call one of the overloads of the <xref:System.Threading.Tasks.Task.WaitAny%2A?displayProperty=nameWithType> method. The following example creates three tasks, each of which sleeps for an interval determine by a random number generator. The <xref:System.Threading.Tasks.Task.WaitAny%28System.Threading.Tasks.Task%5B%5D%29> method waits for the first task to complete. The example then displays information about the status of all three tasks. 
+ In some cases, you may want to wait for the first of a series of executing tasks to complete, but don't care which task it is. For this purpose, you can call one of the overloads of the <xref:System.Threading.Tasks.Task.WaitAny%2A?displayProperty=nameWithType> method. The following example creates three tasks, each of which sleeps for an interval determined by a random number generator. The <xref:System.Threading.Tasks.Task.WaitAny%28System.Threading.Tasks.Task%5B%5D%29> method waits for the first task to complete. The example then displays information about the status of all three tasks. 
  
  [!code-csharp[System.Threading.Tasks.Task#10](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task/cs/WhenAny1.cs#10)]
  [!code-vb[System.Threading.Tasks.Task#10](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/WaitAny1.vb#10)] 

xml/System.Threading.Tasks/ValueTask.xml

@@ -64,6 +64,10 @@ Using a `ValueTask` instead of a <xref:System.Threading.Tasks.Task> introduces s
 
 > [!NOTE]
 > The use of the `ValueTask` type is supported starting with C# 7.0 and is not supported by any version of Visual Basic.
+
+> [!NOTE]
+> An instance created with the parameterless constructor or by the `default(ValueTask)` syntax (a zero-initialized structure) represents a synchronously, successfully completed operation.
+
  ]]></format>
  </remarks>
  </Docs>

xml/System.Threading.Tasks/ValueTask`1.xml

@@ -77,6 +77,10 @@ As such, the default choice for any asynchronous method should be to return a <x
 
 > [!NOTE]
 > The use of the <xref:System.Threading.Tasks.ValueTask%601> type is supported starting with C# 7.0, and is not supported by any version of Visual Basic.
+
+> [!NOTE]
+> An instance created with the parameterless constructor or by the `default(ValueTask<TResult>)` syntax (a zero-initialized structure) represents a synchronously, successfully completed operation with a result of `default(TResult)`.
+
  ]]></format>
  </remarks>
  </Docs>