Merge branch 'master' into linq-to-xml

Author: mairaw

.openpublishing.redirection.json

@@ -446,6 +446,10 @@
       "source_path": "docs/core/tutorials/cli-console-app-tutorial-advanced.md",
       "redirect_url": "/dotnet/core/tutorials"
     },
+    {
+      "source_path": "docs/core/tutorials/consuming-library-with-visual-studio.md",
+      "redirect_url": "/nuget/quickstart/install-and-use-a-package-in-visual-studio"
+    },
     {
       "source_path": "docs/core/tutorials/create-custom-template.md",
       "redirect_url": "/dotnet/core/tutorials/cli-templates-create-item-template"
@@ -4349,7 +4353,7 @@
     },
     {
       "source_path": "docs/visual-basic/sample-applications.md",
-      "redirect_url": "https://github.com/dotnet/samples/tree/master/snippets/visualbasic"
+      "redirect_url": "https://docs.microsoft.com/samples/browse/?languages=vb"
     },
     {
       "source_path": "docs/visual-basic/developing-apps/customizing-extending-my/customizing-projects-and-extending-my.md",

docs/architecture/cloud-native/index.md

@@ -29,7 +29,7 @@ This book is provided "as-is" and expresses the author's views and opinions. The
 
 Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.
 
-Microsoft and the trademarks listed at https://www.microsoft.com on the "Trademarks" webpage are trademarks of the Microsoft group of companies.
+Microsoft and the trademarks listed at [https://www.microsoft.com](https://www.microsoft.com) on the "Trademarks" webpage are trademarks of the Microsoft group of companies.
 
 Mac and macOS are trademarks of Apple Inc.
 

docs/core/toc.yml

@@ -81,59 +81,90 @@
   href: compatibility/
 - name: Tutorials
   items:
-  - name: Overview
-    href: tutorials/index.md
-  - name: Get started with .NET Core using Visual Studio
-    href: tutorials/with-visual-studio.md
-  - name: Get started with .NET Core using Visual Studio Code
-    href: tutorials/with-visual-studio-code.md
-  - name: Get started with .NET Core using the CLI
-    href: tutorials/cli-create-console-app.md
-  - name: Get started with .NET Core using Visual Studio Code on macOS
-    href: tutorials/using-on-macos.md
-  - name: Get started with .NET Core using Visual Studio for Mac
-    href: tutorials/using-on-mac-vs.md
-  - name: Debug an application using Visual Studio
-    href: tutorials/debugging-with-visual-studio.md
-  - name: Publish an application with Visual Studio
-    href: tutorials/publishing-with-visual-studio.md
-  - name: Create a .NET Standard library in Visual Studio
-    href: tutorials/library-with-visual-studio.md
-  - name: Test a .NET Standard library in Visual Studio
-    href: tutorials/testing-library-with-visual-studio.md
-  - name: Consume a .NET Standard library in Visual Studio
-    href: tutorials/consuming-library-with-visual-studio.md
-  - name: Build a complete .NET Core solution on macOS
-    href: tutorials/using-on-mac-vs-full-solution.md
-  - name: Organize and test projects with the .NET Core CLI
-    href: tutorials/testing-with-cli.md
-  - name: Develop libraries with cross-platform tools
-    href: tutorials/libraries.md
-  - name: Create a .NET Core app with plugins
-    href: tutorials/creating-app-with-plugin-support.md
-  - name: Develop ASP.NET Core apps
-    href: tutorials/aspnet-core.md
-  - name: Host .NET Core from native code
-    href: tutorials/netcore-hosting.md
-  - name: Create templates for the CLI
+  - name: Use Visual Studio
+    items:
+    - name: Create a console app
+      href: tutorials/with-visual-studio.md
+      displayName: tutorials, visual studio, vs
+    - name: Debug an app
+      href: tutorials/debugging-with-visual-studio.md
+      displayName: tutorials, visual studio, vs
+    - name: Publish an app
+      href: tutorials/publishing-with-visual-studio.md
+      displayName: tutorials, visual studio, vs
+    - name: Create a library
+      href: tutorials/library-with-visual-studio.md
+      displayName: tutorials, visual studio, vs
+    - name: Unit test a library
+      href: tutorials/testing-library-with-visual-studio.md
+      displayName: tutorials, visual studio, vs
+    - name: Install and use a package
+      href: /nuget/quickstart/install-and-use-a-package-in-visual-studio
+      displayName: tutorials, visual studio, vs
+    - name: Create and publish a package
+      href: /nuget/quickstart/create-and-publish-a-package-using-visual-studio
+      displayName: tutorials, visual studio, vs
+  - name: Use Visual Studio Code
+    items:
+    - name: Create a console app
+      href: tutorials/with-visual-studio-code.md
+      displayName: tutorials, visual studio code, vs code, cli
+    - name: Create a console app and publish it
+      href: tutorials/cli-create-console-app.md
+      displayName: tutorials, cli
+    - name: Create a library and unit test it - macOS
+      href: tutorials/using-on-macos.md
+      displayName: tutorials, visual studio code, vs code, cli
+    - name: Install and use a package
+      href: /nuget/quickstart/install-and-use-a-package-using-the-dotnet-cli
+      displayName: tutorials, cli
+    - name: Create and publish a package
+      href: /nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli
+      displayName: tutorials
+  - name: Use Visual Studio for Mac
     items:
-    - name: 1 - Create an item template
-      href: tutorials/cli-templates-create-item-template.md
-    - name: 2 - Create a project template
-      href: tutorials/cli-templates-create-project-template.md
-    - name: 3 - Create a template pack
-      href: tutorials/cli-templates-create-template-pack.md
-  - name: Create tools for the CLI
+    - name: Create a console app
+      href: tutorials/using-on-mac-vs.md
+      displayName: tutorials
+    - name: Create a library and unit test it
+      href: tutorials/using-on-mac-vs-full-solution.md
+      displayName: tutorials
+    - name: Install and use a package
+      href: /nuget/quickstart/install-and-use-a-package-in-visual-studio-mac
+      displayName: tutorials
+  - name: Advanced topics
     items:
-    - name: 1 - Create a tool
-      displayName: tools, tutorials
-      href: tools/global-tools-how-to-create.md
-    - name: 2 - Use a global tool
-      displayName: tools, tutorials
-      href: tools/global-tools-how-to-use.md
-    - name: 3 - Use a local tool
-      href: tools/local-tools-how-to-use.md
-      displayName: tools, tutorials
+    - name: Unit test an app with xUnit
+      href: tutorials/testing-with-cli.md
+      displayName: tutorials, cli
+    - name: How to create libraries
+      href: tutorials/libraries.md
+    - name: Create templates for the CLI
+      items:
+      - name: 1 - Create an item template
+        href: tutorials/cli-templates-create-item-template.md
+        displayName: tutorials, cli
+      - name: 2 - Create a project template
+        href: tutorials/cli-templates-create-project-template.md
+        displayName: tutorials, cli
+      - name: 3 - Create a template pack
+        href: tutorials/cli-templates-create-template-pack.md
+        displayName: tutorials, cli
+    - name: Create tools for the CLI
+      items:
+      - name: 1 - Create a tool
+        displayName: tools, tutorials, cli
+        href: tools/global-tools-how-to-create.md
+      - name: 2 - Use a global tool
+        displayName: tools, tutorials, cli
+        href: tools/global-tools-how-to-use.md
+      - name: 3 - Use a local tool
+        href: tools/local-tools-how-to-use.md
+        displayName: tools, tutorials, cli
+    - name: Create an app with plugins
+      href: tutorials/creating-app-with-plugin-support.md
+  - name: More tutorials
+    href: tutorials/index.md
 - name: Project SDKs
   items:
   - name: Overview
@@ -441,6 +472,8 @@
   href: distribution-packaging.md
 - name: Expose .NET Core components to COM
   href: native-interop/expose-components-to-com.md
+- name: Host .NET Core from native code
+  href: tutorials/netcore-hosting.md
 - name: Packages, metapackages, and frameworks
   href: packages.md
 - name: Continuous integration

docs/core/tools/custom-templates.md

@@ -91,7 +91,7 @@ The *mytemplate* folder is an installable template pack. Once the pack is instal
 
 ## Packing a template into a NuGet package (nupkg file)
 
-A custom template is packed with the [dotnet pack](dotnet-pack.md) command and a *.csproj* file. Alternatively, [NuGet](https://docs.microsoft.com/nuget/tools/nuget-exe-cli-reference) can be used with the [nuget pack](https://docs.microsoft.com/nuget/tools/cli-ref-pack) command along with a *.nuspec* file. However, NuGet requires the .NET Framework on Windows and [Mono](https://www.mono-project.com/) on Linux and MacOS.
+A custom template is packed with the [dotnet pack](dotnet-pack.md) command and a *.csproj* file. Alternatively, [NuGet](https://docs.microsoft.com/nuget/tools/nuget-exe-cli-reference) can be used with the [nuget pack](https://docs.microsoft.com/nuget/tools/cli-ref-pack) command along with a *.nuspec* file. However, NuGet requires the .NET Framework on Windows and [Mono](https://www.mono-project.com/) on Linux and macOS.
 
 The *.csproj* file is slightly different from a traditional code-project *.csproj* file. Note the following settings:
 

docs/core/tools/dotnet-add-package.md

@@ -85,7 +85,7 @@ The *ToDo.csproj* file now contains a [`<PackageReference>`](/nuget/consume-pack
 
 - **`-s|--source <SOURCE>`**
 
-  The NuGet package source to use during the restore operation.
+  The URI of the NuGet package source to use during the restore operation.
 
 - **`-v|--version <VERSION>`**
 

docs/core/tools/dotnet-build.md

@@ -17,8 +17,8 @@ ms.date: 02/14/2020
 dotnet build [<PROJECT>|<SOLUTION>] [-c|--configuration <CONFIGURATION>]
     [-f|--framework <FRAMEWORK>] [--force] [--interactive] [--no-dependencies]
     [--no-incremental] [--no-restore] [--nologo] [-o|--output <OUTPUT_DIRECTORY>]
-    [-r|--runtime <RUNTIME_IDENTIFIER>] [-v|--verbosity <LEVEL>]
-    [--version-suffix <VERSION_SUFFIX>]
+    [-r|--runtime <RUNTIME_IDENTIFIER>] [-s|--source <SOURCE>]
+    [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]
 
 dotnet build -h|--help
 ```
@@ -115,6 +115,10 @@ The project or solution file to build. If a project or solution file isn't speci
 
   Specifies the target runtime. For a list of Runtime Identifiers (RIDs), see the [RID catalog](../rid-catalog.md).
 
+- **`-s|--source <SOURCE>`**
+
+  The URI of the NuGet package source to use during the restore operation.
+
 - **`-v|--verbosity <LEVEL>`**
 
   Sets the MSBuild verbosity level. Allowed values are `q[uiet]`, `m[inimal]`, `n[ormal]`, `d[etailed]`, and `diag[nostic]`. The default is `minimal`.

docs/core/tools/dotnet-install-script.md

@@ -25,7 +25,7 @@ dotnet-install.ps1 [-Architecture <ARCHITECTURE>] [-AzureFeed]
 dotnet-install.ps1 -Help
 ```
 
-Linux/macOs:
+Linux/macOS:
 
 ```bash
 dotnet-install.sh  [--architecture <ARCHITECTURE>] [--azure-feed]
@@ -94,7 +94,7 @@ The install scripts do not update the registry on Windows. They just download th
 
 - **`-InstallDir|--install-dir <DIRECTORY>`**
 
-  Specifies the installation path. The directory is created if it doesn't exist. The default value is *%LocalAppData%\Microsoft\dotnet*. Binaries are placed directly in this directory.
+  Specifies the installation path. The directory is created if it doesn't exist. The default value is *%LocalAppData%\Microsoft\dotnet* on Windows and */usr/share/dotnet* on Linux/macOS. Binaries are placed directly in this directory.
 
 - **`-JSonFile|--jsonfile <JSONFILE>`**
 

docs/core/tools/dotnet-list-reference.md

@@ -14,20 +14,20 @@ ms.date: 02/14/2020
 ## Synopsis
 
 ```dotnetcli
-dotnet list [<PROJECT>|<SOLUTION>] reference
+dotnet list [<PROJECT>] reference
 
 dotnet list -h|--help
 ```
 
 ## Description
 
-The `dotnet list reference` command provides a convenient option to list project references for a given project or solution.
+The `dotnet list reference` command provides a convenient option to list project references for a given project.
 
 ## Arguments
 
-* **`PROJECT | SOLUTION`**
+* **`PROJECT`**
 
-  Specifies the project or solution file to use for listing references. If not specified, the command searches the current directory for a project file.
+  The project file to operate on. If a file is not specified, the command will search the current directory for one.
 
 ## Options
 

docs/core/tools/dotnet-restore.md

@@ -19,7 +19,7 @@ dotnet restore [<ROOT>] [--configfile <FILE>] [--disable-parallel]
     [--interactive] [--lock-file-path <LOCK_FILE_PATH>] [--locked-mode]
     [--no-cache] [--no-dependencies] [--packages <PACKAGES_DIRECTORY>]
     [-r|--runtime <RUNTIME_IDENTIFIER>] [-s|--source <SOURCE>]
-    [--use-lockfile] [-v|--verbosity <LEVEL>]
+    [--use-lock-file] [-v|--verbosity <LEVEL>]
 
 dotnet restore -h|--help
 ```
@@ -137,9 +137,9 @@ There are three specific settings that `dotnet restore` ignores:
 
 - **`-s|--source <SOURCE>`**
 
-  Specifies a NuGet package source to use during the restore operation. This setting overrides all of the sources specified in the *nuget.config* files. Multiple sources can be provided by specifying this option multiple times.
+  Specifies the URI of the NuGet package source to use during the restore operation. This setting overrides all of the sources specified in the *nuget.config* files. Multiple sources can be provided by specifying this option multiple times.
 
-- **`--use-lockfile`**
+- **`--use-lock-file`**
 
   Enables project lock file to be generated and used with restore.
 

docs/core/tools/dotnet-test.md

@@ -73,6 +73,10 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 - **`--collect <DATA_COLLECTOR_FRIENDLY_NAME>`**
 
   Enables data collector for the test run. For more information, see [Monitor and analyze test run](https://aka.ms/vstest-collect).
+  
+  To collect code coverage on any platform that is supported by .NET Core, install [Coverlet](https://github.com/coverlet-coverage/coverlet/blob/master/README.md) and use the `--collect:"XPlat Code Coverage"` option.
+
+  On Windows, you can collect code coverage by using the `--collect "Code Coverage"` option. This option generates a *.coverage* file, which can be opened in Visual Studio 2019 Enterprise. For more information, see [Use code coverage](/visualstudio/test/using-code-coverage-to-determine-how-much-code-is-being-tested) and [Customize code coverage analysis](/visualstudio/test/customizing-code-coverage-analysis).
 
 - **`-d|--diag <PATH_TO_DIAGNOSTICS_FILE>`**
 
@@ -112,7 +116,7 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 
 - **`-o|--output <OUTPUT_DIRECTORY>`**
 
-  Directory in which to find the binaries to run. If not specified, the default path is `./bin/<configuration>/<framework>/`.  For projects with multiple target frameworks (via the `TargetFrameworks` property), you also need to define `--framework` when you specify this option. `dotnet test` always run tests from the output directory. You can use <xref:System.AppDomain.BaseDirectory%2A?displayProperty=nameWithType> to consume test assets in the output directory.
+  Directory in which to find the binaries to run. If not specified, the default path is `./bin/<configuration>/<framework>/`.  For projects with multiple target frameworks (via the `TargetFrameworks` property), you also need to define `--framework` when you specify this option. `dotnet test` always runs tests from the output directory. You can use <xref:System.AppDomain.BaseDirectory%2A?displayProperty=nameWithType> to consume test assets in the output directory.
 
 - **`-r|--results-directory <PATH>`**
 
@@ -165,6 +169,18 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
   dotnet test --logger trx
   ```
 
+- Run the tests in the project in the current directory, and generate a code coverage file (after installing [Coverlet](https://github.com/tonerdo/coverlet/blob/master/README.md)):
+
+  ```dotnetcli
+  dotnet test --collect:"XPlat Code Coverage"
+  ```
+
+- Run the tests in the project in the current directory, and generate a code coverage file (Windows only):
+
+  ```dotnetcli
+  dotnet test --collect "Code Coverage"
+  ```
+
 - Run the tests in the project in the current directory, and log with detailed verbosity to the console:
 
   ```dotnetcli
@@ -189,6 +205,7 @@ Where `Microsoft.NET.Test.Sdk` is the test host, `xunit` is the test framework.
 | -------------- | --------------------------------------------------------------------------------------------------------- |
 | MSTest         | <ul><li>FullyQualifiedName</li><li>Name</li><li>ClassName</li><li>Priority</li><li>TestCategory</li></ul> |
 | xUnit          | <ul><li>FullyQualifiedName</li><li>DisplayName</li><li>Traits</li></ul>                                   |
+| NUnit          | <ul><li>FullyQualifiedName</li><li>Name</li><li>TestCategory</li><li>Priority</li></ul>                                   |
 
 The `<operator>` describes the relationship between the property and the value: