Merge pull request NuGet#1031 from NuGet/master

Merging Plugin changes to live.

Author: anangaur

docs/consume-packages/managing-the-global-packages-and-cache-folders.md

@@ -17,6 +17,7 @@ Whenever you install, update, or restore a package, NuGet manages packages and p
 | global&#8209;packages | The *global-packages* folder is where NuGet installs any downloaded package. Each package is fully expanded into a subfolder that matches the package identifier and version number. Projects using the PackageReference format always use packages directly from this folder. When using the `packages.config`, packages are installed to the *global-packages* folder, then copied into the project's `packages` folder.<br/><ul><li>Windows: `%userprofile%\.nuget\packages`</li><li>Mac/Linux: `~/.nuget/packages`</li><li>Override using the NUGET_PACKAGES environment variable, the `globalPackagesFolder` or `repositoryPath` [configuration settings](../reference/nuget-config-file.md#config-section) (when using PackageReference and `packages.config`, respectively), or the `RestorePackagesPath` MSBuild property (MSBuild only). The environment variable takes precedence over the configuration setting.</li></ul> |
 | http&#8209;cache | The Visual Studio Package Manager (NuGet 3.x+) and the `dotnet` tool store copies of downloaded packages in this cache (saved as `.dat` files), organized into subfolders for each package source. Packages are not expanded, and the cache has an expiration time of 30 minutes.<br/><ul><li>Windows: `%localappdata%\NuGet\v3-cache`</li><li>Mac/Linux: `~/.local/share/NuGet/v3-cache`</li><li>Override using the NUGET_HTTP_CACHE_PATH environment variable.</li></ul> |
 | temp | A folder where NuGet stores temporary files during its various operations.<br/><li>Windows: `%temp%\NuGetScratch`</li><li>Mac/Linux: `/tmp/NuGetScratch`</li></ul> |
+| plugins-cache **4.8+** | A folder where NuGet stores the results from the operation claims request.<br/><ul><li>Windows: `%localappdata%\NuGet\plugins-cache`</li><li>Mac/Linux: `~/.local/share/NuGet/plugins-cache`</li><li>Override using the NUGET_PLUGINS_CACHE_PATH environment variable.</li></ul> |
 
 > [!Note]
 > NuGet 3.5 and earlier uses *packages-cache* instead of the *http-cache*, which is located in `%localappdata%\NuGet\Cache`.
@@ -29,38 +30,40 @@ For more information, see [What happens when a package is installed](ways-to-ins
 
 ## Viewing folder locations
 
-You can view folder locations using the [dotnet nuget locals command](/dotnet/core/tools/dotnet-nuget-locals):
+You can view locations using the [nuget locals command](../tools/cli-ref-locals.md):
 
 ```cli
-dotnet nuget locals all --list
+# Display locals for all folders: global-packages, http cache, temp and plugins cache
+nuget locals all -list
 ```
 
-Typical output (Mac/Linux; "user1" is the current username):
+Typical output (Windows; "user1" is the current username):
 
 ```output
-info : http-cache: /home/user1/.local/share/NuGet/v3-cache
-info : global-packages: /home/user1/.nuget/packages/
-info : temp: /tmp/NuGetScratch
+http-cache: C:\Users\user1\AppData\Local\NuGet\v3-cache
+global-packages: C:\Users\user1\.nuget\packages\
+temp: C:\Users\user1\AppData\Local\Temp\NuGetScratch
+plugins-cache: C:\Users\user1\AppData\Local\NuGet\plugins-cache
 ```
 
-To display the location of a single folder, use `http-cache`, `global-packages`, or `temp` instead of `all`. 
+(`package-cache` is used in NuGet 2.x and appears with NuGet 3.5 and earlier.)
 
-You also view locations using the [nuget locals command](../tools/cli-ref-locals.md):
+You can also view folder locations using the [dotnet nuget locals command](/dotnet/core/tools/dotnet-nuget-locals):
 
 ```cli
-# Display locals for all folders: global-packages, cache, and temp
-nuget locals all -list
+dotnet nuget locals all --list
 ```
 
-Typical output (Windows; "user1" is the current username):
+Typical output (Mac/Linux; "user1" is the current username):
 
 ```output
-http-cache: C:\Users\user1\AppData\Local\NuGet\v3-cache
-global-packages: C:\Users\user1\.nuget\packages\
-temp: C:\Users\user1\AppData\Local\Temp\NuGetScratch
+info : http-cache: /home/user1/.local/share/NuGet/v3-cache
+info : global-packages: /home/user1/.nuget/packages/
+info : temp: /tmp/NuGetScratch
+info : plugins-cache: /home/user1/.local/share/NuGet/plugins-cache
 ```
 
-(`package-cache` is used in NuGet 2.x and appears with NuGet 3.5 and earlier.)
+To display the location of a single folder, use `http-cache`, `global-packages`, `temp`, or `plugins-cache` instead of `all`.
 
 ## Clearing local folders
 
@@ -82,6 +85,10 @@ nuget locals global-packages -clear
 dotnet nuget locals temp --clear
 nuget locals temp -clear
 
+# Clear the plugins cache (use either command)
+dotnet nuget locals plugins-cache --clear
+nuget locals plugins-cache -clear
+
 # Clear all caches (use either command)
 dotnet nuget locals all --clear
 nuget locals all -clear

docs/quickstart/create-and-publish-a-package-using-visual-studio.md

@@ -145,6 +145,26 @@ This step is an alternative to using `nuget.exe`.
 
 [!INCLUDE [publish-manage](includes/publish-manage.md)]
 
+## Adding a readme and other files
+
+To directly specify files to include in the package, edit the project file and use the `content` property:
+
+```xml
+<ItemGroup>
+  <Content Include="readme.txt">
+    <Pack>true</Pack>
+    <PackagePath>\</PackagePath>
+  </Content>
+</ItemGroup>
+```
+
+This will include a file named `readme.txt` in the package root. Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Readme files are not displayed for packages installed as dependencies). For example, here's how the readme for the HtmlAgilityPack package appears:
+
+![The display of a readme file for a NuGet package upon installation](../create-packages/media/Create_01-ShowReadme.png)
+
+> [!Note]
+> Merely adding the readme.txt at the project root will not result in it being included in the resulting package.
+
 ## Related topics
 
 - [Create a Package](../create-packages/creating-a-package.md)

docs/reference/extensibility/NuGet-Credential-Providers-for-Visual-Studio.md

@@ -15,10 +15,13 @@ After you install a NuGet credential provider for Visual Studio, the NuGet Visua
 
 A sample implementation can be found in [the VsCredentialProvider sample](https://github.com/NuGet/Samples/tree/master/VsCredentialProvider).
 
+Starting with 4.8+ NuGet in Visual Studio supports the new cross platform authentication plugins as well, but they are not the recommended approach for performance reasons.
+
 > [!Note]
-> NuGet credential providers for Visual Studio must be installed as a regular Visual Studio extension and will require [Visual Studio 2017](https://aka.ms/vs/15/preview/vs_enterprise) (currently in preview) or above.
+> NuGet credential providers for Visual Studio must be installed as a regular Visual Studio extension and will require [Visual Studio 2017](http://aka.ms/vs/15/release/vs_enterprise.exe) or above.
 >
 > NuGet credential providers for Visual Studio work only in Visual Studio (not in dotnet restore or nuget.exe). For credential providers with nuget.exe, see [nuget.exe Credential Providers](nuget-exe-Credential-providers.md).
+> For credential providers in dotnet and msbuild see [NuGet cross platform plugins](#NuGet-Cross-Platform-Authentication-Plugin.md)
 
 ## Available NuGet credential providers for Visual Studio
 
@@ -38,7 +41,8 @@ During credential acquisition, the credential service will try credential provid
 
 1. Credentials will be fetched from NuGet configuration files (using the built-in `SettingsCredentialProvider`).
 1. If the package source is on Visual Studio Team Services, the `VisualStudioAccountProvider` will be used.
-1. All other plug-in credential providers will be tried sequentially.
+1. All other plug-in Visual Studio credential providers will be tried sequentially.
+1. Try to use all NuGet cross platform credential providers sequentially.
 1. If no credentials have been acquired yet, the user will be prompted for credentials using a standard basic authentication dialog.
 
 ### Implementing IVsCredentialProvider.GetCredentialsAsync

docs/reference/extensibility/NuGet-Cross-Platform-Authentication-Plugin.md

@@ -0,0 +1,74 @@
+---
+title: NuGet cross platform authentication plugin
+description: NuGet cross platform authentication plugins for NuGet.exe, dotnet.exe, msbuild.exe and Visual Studio
+author: nkolev92
+ms.author: nikolev
+manager: rrelyea
+ms.date: 07/01/2018
+ms.topic: conceptual
+---
+
+# NuGet cross platform authentication plugin
+
+In version 4.8+, all NuGet clients (NuGet.exe, Visual Studio, dotnet.exe and MSBuild.exe) can use an authentication plugin built on top of the [NuGet cross platform plugins](NuGet-Cross-Platform-Plugins.md) model.
+
+## Available NuGet cross platform authentication plugins
+
+TBD - Link to the VSTS provider
+
+## Authentication in dotnet.exe
+
+Visual Studio and NuGet.exe are by default interactive. NuGet.exe contains a switch to make it [non interactive](../../tools/nuget-exe-CLI-Reference.md).
+Additionally the NuGet.exe and Visual Studio plugins prompt the user for input.
+In dotnet.exe there is no prompting and the default is non interactive.
+
+The authentication mechanism in dotnet.exe is device flow. When the restore or add package operation is run interactively, the operation blocks and instructions to the user how to complete the authentications will be provided on the command line.
+When the user completes the authentication the operation will continue.
+
+To make the operation interactive, one should pass `--interactive`.
+Currently only the explicit `dotnet restore` and `dotnet add package` commands support an interactive switch.
+There is no interactive switch on `dotnet build` and `dotnet publish`.
+
+## Authentication in MSBuild
+
+Similar to dotnet.exe, MSBuild.exe is by default non interactive the MSBuild.exe authentication mechanism is device flow.
+To allow the restore to pause and wait for authentication, call restore with `msbuild /t:restore /p:NuGetInteractive="true"`.
+
+## Creating a cross platform authentication plugin
+
+A sample implementation can be found in [MSCredProvider plugin](https://github.com/Microsoft/mscredprovider).
+
+It's very important that the plugins conforms to the security requirements set forth by the NuGet client tools.
+The minimum required version for a plugin to be an authentication plugin is *2.0.0*.
+NuGet will perform the handshake with the plugin and query for the supported operation claims.
+Please refer to the NuGet cross platform plugin [protocol messages](NuGet-Cross-Platform-Plugins.md#protocol-messages-index) for more details about the specific messages.
+
+NuGet will set the log level and provide proxy information to the plugin when applicable.
+Logging to the NuGet console is only acceptable after NuGet has set the log level to the plugin.
+
+- .NET Framework plugin authentication behavior
+
+In .NET Framework, the plugins are allowed to prompt a user for input, in the form of a dialog.
+
+- .NET Core plugin authentication behavior
+
+In .NET Core, a dialog cannot be shown. The plugins should use device flow to authenticate.
+The plugin can send log messages to NuGet with instructions to the user.
+Note that logging is available after the log level has been set to the plugin.
+NuGet will not take any interactive input from the command line.
+
+When the client calls the plugin with a Get Authentication Credentials, the plugins need to conform to the interactivity switch and respect the dialog switch. 
+
+The following table summarizes how the plugin should behave for all combinations.
+
+| IsNonInteractive | CanShowDialog | Plugin behavior |
+| ---------------- | ------------- | --------------- |
+| true | true | The IsNonInteractive switch takes precedence over the dialog switch. The plugin is not allowed to pop a dialog. This combination is only valid for .NET Framework plugins |
+| true | false | The IsNonInteractive switch takes precedence over the dialog switch. The plugin is not allowed to block. This combination is only valid for .NET Core plugins |
+| false | true | The plugin should show a dialog. This combination is only valid for .NET Framework plugins |
+| false | false | The plugin should/can not show a dialog. The plugin should use device flow to authenticate by logging an instruction message via the logger. This combination is only valid for .NET Core plugins |
+
+Please refer to the following specs before writing a plugin.
+
+- [NuGet Package Download Plugin](https://github.com/NuGet/Home/wiki/NuGet-Package-Download-Plugin)
+- [NuGet cross plat authentication plugin](https://github.com/NuGet/Home/wiki/NuGet-cross-plat-authentication-plugin)