Merge pull request NuGet#589 from NuGet/master

Merge master to live

Author: Kraig Brockschmidt

docs/API/package-base-address-resource.md

@@ -113,10 +113,10 @@ GET {@id}/{LOWER_ID}/{LOWER_VERSION}/{LOWER_ID}.{LOWER_VERSION}.nupkg
 
 ### Request parameters
 
-Name          | In     | Type    | Required | Notes
-------------- | ------ | ------- | -------- | -----
-LOWER_ID      | URL    | string  | yes      | The package ID, lowercase
-LOWER_VERSION | URL    | integer | yes      | The package version, normalized and lowercased
+Name          | In     | Type   | Required | Notes
+------------- | ------ | ------ | -------- | -----
+LOWER_ID      | URL    | string | yes      | The package ID, lowercase
+LOWER_VERSION | URL    | string | yes      | The package version, normalized and lowercased
 
 Both `LOWER_ID` and `LOWER_VERSION` are lowercased using the rules implemented by .NET's
 [`System.String.ToLowerInvariant()`](https://msdn.microsoft.com/en-us/library/system.string.tolowerinvariant.aspx)

docs/API/registration-base-url-resource.md

@@ -139,7 +139,7 @@ Name   | Type             | Required | Notes
 count  | integer          | yes      | The number of registration leaves in the page
 items  | array of objects | no       | The array of registration leaves and their associate metadata
 lower  | string           | yes      | The lowest SemVer 2.0.0 version in the page (inclusive)
-parent | string           | yes      | The URL to the registration index
+parent | string           | no       | The URL to the registration index
 upper  | string           | yes      | The highest SemVer 2.0.0 version in the page (inclusive)
 
 The `lower` and `upper` bounds of the page object are useful when the metadata for a specific page version is needed.
@@ -148,6 +148,8 @@ These bounds can be used to fetch the only registration page needed. The version
 build metadata. As with all versions in the NuGet ecosystem, comparison of version strings is implemented using
 [SemVer 2.0.0's version precedence rules](http://semver.org/spec/v2.0.0.html#spec-item-11).
 
+The `parent` property will only appear if the registration page object has the `items` property.
+
 If the `items` property is not present in the registration page object, the URL specified in the `@id` must be used to
 fetch metadata about individual package versions. The `items` array is sometimes excluded from the page
 object as an optimization. If the number of versions of a single package ID is very large, then the registration index

docs/Consume-Packages/Configuring-NuGet-Behavior.md

@@ -129,6 +129,12 @@ By default, NuGet 2.7 and earlier resolves the highest *patch* version (using th
 The `packages.config` process for resolving dependencies gets complicated for larger dependency graphs. Each new package installation requires a traversal of the whole graph and raises the chance for version conflicts. When a conflict occurs, installation is stopped, leaving the project in an indeterminate state, especially with potential modifications to the project file itself. This is not an issue when using other package reference formats.
 
 
+## Managing dependency assets
+
+When using the `project.json` or PackageReference formats, you can control which assets from dependencies flow into the top-level project. For details, see [project.json](../Schema/project-json.md) and [Package references in project files](Package-References-in-Project-Files.md#controlling-dependency-assets).
+
+When the top-level project is itself a package, you also have control over this flow by using the `include` and `exclude` attributes with dependencies listed in the `.nuspec` file. See [.nuspec Reference - Dependencies](../Schema/nuspec.md#dependencies).
+
 ## Excluding references
 
 There are scenarios in which assemblies with the same name might be referenced more than once in a project, producing design-time and build-time errors. Consider a project that contains a custom version of `C.dll`, and references Package C that also contains `C.dll`. At the same time, the project also depends on Package B which also depends on Package C and `C.dll`. As a result, NuGet can't determine which `C.dll` to use, but you can't just remove the project's dependency on Package C because Package B also depends on it.

docs/Consume-Packages/Dependency-Resolution.md

@@ -1,31 +1,18 @@
 ---
-# required metadata
-
 title: Overview and workflow of using NuGet packages | Microsoft Docs
 author: kraigb
 ms.author: kraigb
 manager: ghogen
-ms.date: 6/6/2017
+ms.date: 06/06/2017
 ms.topic: article
 ms.prod: nuget
-#ms.service:
 ms.technology: null
 ms.assetid: 3c60f920-457d-4f43-9efe-210c514e5242
-
-# optional metadata
-
 description: An overview of the process of consuming NuGet packages in a project, with links to other specific parts of the process.
 keywords: NuGet package consumption, NuGet consumption overview, NuGet consumption workflow, package consumption workflow, package consumption overview
-#ROBOTS:
-#audience:
-#ms.devlang:
 ms.reviewer:
 - karann-msft
 - unniravindranathan
-#ms.suite:
-#ms.tgt_pltfrm:
-#ms.custom:
-
 ---
 
 # Package consumption workflow

docs/Consume-Packages/Overview-and-Workflow.md

@@ -1,7 +1,7 @@
 ---
 # required metadata
 
-title: Troubleshooting NuGet Package Restore in Visual STudio | Microsoft Docs
+title: Troubleshooting NuGet Package Restore in Visual Studio | Microsoft Docs
 author: kraigb
 ms.author: kraigb
 manager: ghogen

docs/Consume-Packages/Package-restore-troubleshooting.md

@@ -145,7 +145,7 @@ The following is a typical (but fictitious) `.nuspec` file, with comments descri
 </package>
 ```
 
-For details on declaring dependencies and specifying version numbers, see [Package versioning](../reference/package-versioning.md).
+For details on declaring dependencies and specifying version numbers, see [Package versioning](../reference/package-versioning.md). It is also possible to surface assets from dependencies directly in the package by using the `include` and `exclude` attributes on the `dependency` element. See [.nuspec Reference - Dependencies](../Schema/nuspec.md#dependencies).
 
 Because the manifest is included in the package created from it, you can find any number of additional examples by examining existing packages. A good source is the global package cache on your machine, the location of which is returned by the following command:
 

docs/Create-Packages/Creating-a-Package.md

@@ -5,7 +5,7 @@ title: Overview and workflow of creating NuGet packages | Microsoft Docs
 author: kraigb
 ms.author: kraigb
 manager: ghogen
-ms.date: 7/26/2017
+ms.date: 07/26/2017
 ms.topic: article
 ms.prod: nuget
 ms.technology: null

docs/Create-Packages/Overview-and-Workflow.md

@@ -69,7 +69,7 @@ Next, you can either upload the package through the nuget.org web portal, push t
 4. Push your package to NuGet Gallery using the command:
 
     ```
-    nuget push YourPackage.nupkg -Source https://www.nuget.org/api/v2/package
+    nuget push YourPackage.nupkg -Source https://api.nuget.org/v3/index.json
     ```
 
 5. Before being made public, all packages uploaded to nuget.org are scanned for viruses and rejected if any viruses are found. All packages listed on nuget.org are also scanned periodically.

docs/Create-Packages/Publish-a-package.md

@@ -2,28 +2,28 @@
 # required metadata 
 
 title: Installing NuGet client tools | Microsoft Docs
-author: kraigb 
-ms.author: kraigb 
-manager: ghogen 
-ms.date: 10/2/2017
+author: kraigb
+ms.author: kraigb
+manager: ghogen
+ms.date: 10/02/2017
 ms.topic: get-started-article
-ms.prod: nuget 
-ms.technology: null 
-ms.assetid: 683b8b34-a6f4-4d56-b9cd-2483bfbad1ad 
- 
+ms.prod: nuget
+ms.technology: null
+ms.assetid: 683b8b34-a6f4-4d56-b9cd-2483bfbad1ad
+
 # optional metadata
 
 description: Guidance on installing client tools, the command-line interface (CLI), and the Package Manager for Visual Studio.
 keywords: nuget.exe CLI, NuGet client tools, NuGet package manager, NuGet package manager console, NuGet for Visual Studio, NuGet beta channel
-ms.reviewer:  
-- karann-msft 
-- unniravindranathan 
- 
+ms.reviewer:
+- karann-msft
+- unniravindranathan
+
 ---
 
 # Installing NuGet client tools
 
-> [!Tip] 
+> [!Tip]
 > **Looking to install a package? See [Quickstart - Use a package](../Quickstart/Use-a-Package.md).**
 
 There are two primary tools available to help you build, publish and consume NuGet packages:
@@ -33,6 +33,8 @@ There are two primary tools available to help you build, publish and consume NuG
 
     With Visual Studio for Mac, NuGet capabilities are built in directly. See [Including a NuGet package in your project](https://docs.microsoft.com/visualstudio/mac/nuget-walkthrough) for a walkthrough.
 
+    Visual Studio Code at present does not have any built-in NuGet support. Use the NuGet CLI or the [dotnet CLI](../Tools/dotnet-Commands.md).
+
 The NuGet CLI and Package Manager both support the following operations:
 
 - Search packages
@@ -55,7 +57,6 @@ The following capabilities are supported only in the NuGet CLI:
 > Another good tool is the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer), an open-source, stand-alone tool to visually explore, create, and edit NuGet packages. It's very helpful, for example, to make experimental changes to a package structure without having to rebuild the package each time.
 > The cross-platform [.NET Core CLI](https://docs.microsoft.com/dotnet/articles/core/tools/index#installation) toolchain, used for developing .NET Core applications, supports several NuGet commands, such as delete, locals, push, pack, and restore. 
 
-
 ## NuGet CLI
 
 The NuGet command-line interface provides access to all NuGet capabilities, and can be run on Windows, Mac OSX, and Linux as described in the following sections.
@@ -73,15 +74,15 @@ The NuGet command-line interface provides access to all NuGet capabilities, and
 
 - **Chocolatey**: Install the [NuGet.CommandLine](http://chocolatey.org/packages/NuGet.CommandLine) Chocolatey package using the [Chocolatey](http://chocolatey.org) client. 
 
-    ```
+    ```ps
     choco install nuget.commandline
     ```
-    
+
 - **Visual Studio**: Install the [NuGet.CommandLine](http://www.nuget.org/packages/NuGet.CommandLine/) package from the Package Manager Console in Visual Studio.
 
     > [!Note]
     > **For NuGet 2.x users**: Because of breaking changes introduced in NuGet 3.2, [https://nuget.org/nuget.exe](https://nuget.org/nuget.exe) points to the latest stable NuGet 2.x release to prevent continuous integration systems from potentially breaking.
-    
+
 <a name="compatibility-with-mono"></a>
 
 ## Mac OSX and Linux
@@ -110,14 +111,12 @@ On Mac OSX and Linux, there are two ways to run the NuGet CLI:
     - Commands that do not work:
         - update
 
-
 ### Related topics
 
 - [NuGet CLI reference](../tools/nuget-exe-cli-reference.md)
 - [Creating a package](../create-packages/creating-a-package.md)
 - [Publishing a Package](../create-packages/publish-a-package.md)
 
-
 ## NuGet Package Manager in Visual Studio
 
 The NuGet Package Manager is included in every edition of Visual Studio on Windows, 2012 and later. It includes the Package Manager UI ([reference](../tools/package-manager-ui.md)), and the Package Manager Console through which you can access tools that come with certain packages ([reference](../tools/package-manager-console.md)).
@@ -127,8 +126,7 @@ The Visual Studio 2017 installer includes the NuGet Package Manager with any wor
 > [!Note]
 > The console requires [PowerShell 2.0](http://support.microsoft.com/kb/968929), which will already be installed on Windows 7 or higher and Windows Server 2008 R2 or higher.
 >
-> Package Manager Console commands also work only within Visual Studio on Windows. Use the NuGet CLI outside of that environment, including with Visual Studio for Mac.
-
+> Package Manager Console commands also work only within Visual Studio on Windows. Use the NuGet CLI outside of that environment, including with Visual Studio for Mac and Visual Studio Code.
 
 ### Package Manager installation for Visual Studio 2010 and earlier
 

docs/Guides/Install-NuGet.md

@@ -5,7 +5,7 @@ title: Overview of Hosting Your Own NuGet Feeds | Microsoft Docs
 author: kraigb
 ms.author: kraigb
 manager: ghogen
-ms.date: 8/25/2017
+ms.date: 08/25/2017
 ms.topic: article
 ms.prod: nuget
 #ms.service:

docs/Hosting-Packages/Overview.md

@@ -155,8 +155,8 @@ You need to select the **All** source when installing a local package into the p
 
 In most projects where separate projects live in separate folders, this is not a problem as NuGet identifies the `packages.config` and `project.json` files in each project. With NuGet 3.3+ and multiple projects in the same folder, you can insert the name of the project into the `packages.config` or `project.json` filenames as below and NuGet uses that file:
 
-    `packages.config`: use the pattern `packages.{project-name}.config`
-    `project.json`: use the pattern `{project-name}.project.json`
+- `packages.config`: use the pattern `packages.{project-name}.config`
+- `project.json`: use the pattern `{project-name}.project.json`
 
 This is not an issue when using PackageReference, as each project file contains its own list of dependencies.
 
@@ -244,3 +244,8 @@ First, make sure you're using the latest versions of NuGet. If that version cont
 Note: it may be required to set the `HTTP_PROXY` environment variable to `http://127.0.0.1:8888` for routing NuGet traffic through Fiddler.
 
 If that fails, try the [tips mentioned in this StackOverflow post](http://stackoverflow.com/questions/21049908/using-fiddler-to-sniff-visual-studio-2013-requests-proxy-firewall).
+
+**What are the API endpoints for nuget.org?**
+
+V3: `https://api.nuget.org/v3/index.json`
+V2: `https://www.nuget.org/api/v2/` (Note that the V2 API is deprecated and does not work with NuGet 4+.)

docs/Policies/NuGet-FAQ.md

@@ -134,7 +134,7 @@ Once you have a `.nupkg` file, you publish it to nuget.org using the `push` comm
 1. At a command prompt, run the following command, specifying your package name and replacing the key with the value copied in step 4:
 
     ```
-    nuget push AppLogger.1.0.0.0.nupkg 47be3377-c434-4c29-8576-af7f6993a54b -Source https://www.nuget.org/api/v2/package
+    nuget push AppLogger.1.0.0.0.nupkg 47be3377-c434-4c29-8576-af7f6993a54b -Source https://api.nuget.org/v3/index.json
     ```
     
 1. nuget.exe displays the results of the publishing process:

docs/Quickstart/Create-and-Publish-a-Package.md

@@ -1,35 +1,23 @@
 ---
-# required metadata
-
 title: Introductory Guide to Using NuGet Packages | Microsoft Docs
 author: kraigb
 ms.author: kraigb
 manager: ghogen
-ms.date: 10/4/2017
+ms.date: 10/04/2017
 ms.topic: get-started-article
 ms.prod: nuget
 ms.technology: null
 ms.assetid: f31f8259-20a8-4617-880e-5819299372d2
-
-# optional metadata
-
 description: A walkthrough tutorial on the process of installing and using a NuGet package in a project.
 keywords: install NuGet, NuGet package consumption, installing NuGet packages, NuGet package references, using NuGet packages
 ms.reviewer:
 - karann-msft
 - unniravindranathan
-
 ---
 
 # Install and use a package
 
-Installing a package happens in three ways:
-
-| Method | Description | Reference |
-| --- | --- | --- | 
-| nuget.exe CLI: `nuget install <package_name>` | Downloads the package identified by \<package_name\> and expands its contents into a folder in the current directory. No changes are made to any project files. Dependencies are also downloaded and expanded. | [CLI reference](../tools/nuget-exe-CLI-Reference.md) |
-| Package Manager Console (Visual Studio): `Install-Package <package_name>` | Downloads and installs the package into the current project, then update the project file to list the package as a dependency. | [Package Manager Console Guide](../tools/Package-Manager-Console.md) |
-| Package Manager UI (Visual Studio) | Provides a UI through which you can browse, select, and install packages into a project. Updates the project file to list the package as a dependency. | [Package Manager UI Reference](../tools/Package-Manager-UI.md) |
+[!INCLUDE [install-methods](../includes/install-methods.md)]
 
 Once installed, refer to the package in code with `using <namespace>` where \<namespace\> is specific to the package you're using. Once the reference is made, you can call the package through its API.