Add documentation for using MSBuild project SDKs

docs/msbuild/TOC.md

@@ -30,6 +30,7 @@
 #### [How to: Build Specific Targets in Solutions By Using MSBuild.exe](how-to-build-specific-targets-in-solutions-by-using-msbuild-exe.md)
 #### [How to: Build Incrementally](how-to-build-incrementally.md)
 #### [How to: Clean a Build](how-to-clean-a-build.md)
+#### [How to: Reference an MSBuild Project SDK](how-to-use-project-sdk.md)
 ### [MSBuild Tasks](msbuild-tasks.md)
 #### [Task Writing](task-writing.md)
 #### [How to: Ignore Errors in Tasks](how-to-ignore-errors-in-tasks.md)
@@ -89,6 +90,7 @@
 #### [ProjectExtensions Element (MSBuild)](projectextensions-element-msbuild.md)
 #### [Property Element (MSBuild)](property-element-msbuild.md)
 #### [PropertyGroup Element (MSBuild)](propertygroup-element-msbuild.md)
+#### [Sdk Element (MSBuild)](sdk-element-msbuild.md)
 #### [Target Element (MSBuild)](target-element-msbuild.md)
 #### [Task Element (MSBuild)](task-element-msbuild.md)
 #### [TaskBody Element (MSBuild)](taskbody-element-msbuild.md)

docs/msbuild/how-to-use-project-sdk.md

@@ -0,0 +1,104 @@
+---
+title: "How to: Reference an MSBuild Project SDK | Microsoft Docs"
+ms.custom: ""
+ms.date: "01/25/2018"
+ms.reviewer: ""
+ms.suite: ""
+ms.technology: 
+  - "vs-ide-sdk"
+ms.tgt_pltfrm: ""
+ms.topic: "article"
+helpviewer_keywords: 
+  - "MSBuild, SDKs, SDK"
+author: "jeffkl"
+ms.author: "jeffkl"
+manager: angerlic
+ms.workload: 
+  - "multiple"
+---
+# How to: Use MSBuild Project SDKs
+[!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] 15.0 introduced the concept of the "project SDK", which simplifies using software development kits that require properties and targets to be imported.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+    <PropertyGroup>
+        <TargetFramework>net46</TargetFramework>
+    </PropertyGroup>
+</Project>
+```  
+
+During evaluation of the project, [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] adds implicit imports at the top and bottom of your project:
+
+```xml
+<Project>
+    <!-- Implicit top import -->
+    <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />
+
+    <PropertyGroup>
+        <TargetFramework>net46</TargetFramework>
+    </PropertyGroup>
+
+    <!-- Implicit bottom import -->
+    <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
+</Project>  
+```  
+
+## Referencing a Project SDK
+ There are three ways to reference a project SDK
+
+1. Use the `Sdk` attribute on the `<Project/>` element:
+    ```xml
+    <Project Sdk="My.Custom.Sdk">
+        ...
+    </Project>
+    ```
+    An implicit import is added to the top and bottom of the project as discussed above.  The format of the `Sdk` attribute is `Name[/Version]` where Version is optional.  For example, you can specify `My.Custom.Sdk/1.2.3`.
+
+2. Use the top-level `<Sdk/>` element:
+    ```xml
+    <Project>
+        <Sdk Name="My.Custom.Sdk" Version="1.2.3" />
+        ...
+    </Project>
+   ```
+   An implicit import is added to the top and bottom of the project as discussed above.  The `Version` attribute is not required.
+
+3. Use the `<Import/>` element anywhere in your project:
+    ```xml
+    <Project>
+        <PropertyGroup>
+            <MyProperty>Value</MyProperty>
+        </PropertyGroup>
+        <Import Project="Sdk.props" Sdk="My.Custom.Sdk" />
+        ...
+        <Import Project="Sdk.targets" Sdk="My.Custom.Sdk" />
+    </Project>
+   ```
+   Explicitly including the imports in your project allows you full control over the order.
+
+   When using the `<Import/>` element, you can specify an optional `Version` attribute as well.  For example, you can specify `<Import Project="Sdk.props" Sdk="My.Custom.Sdk" Version="1.2.3" />`.
+
+## How Project SDKs are Resolved
+When evaluating the import, [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] dynamically resolves the path to the project SDK based on the name and version you specified.  [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] also has a list of registered SDK resolvers which are plug-ins that locate project SDKs on your machine.  These plug-ins include:
+
+1. A NuGet-based resolver that queries your configured package feeds for NuGet packages that match the ID and version of the SDK you specified.<br/>
+   This resolver is only active if you specified an optional version and it can be used for any custom project SDK.  
+2. A .NET CLI resolver that resolves SDKs that are installed with .NET CLI.<br/>
+   This resolver locates project SDKs such as `Microsoft.NET.Sdk` and `Microsoft.NET.Sdk.Web` which are part of the product.
+3. A default resolver that resolves SDKs that were installed with MSBuild.
+
+The NuGet-based SDK resolver supports specifying a version in your [global.json](https://docs.microsoft.com/en-us/dotnet/core/tools/global-json) that allows you to control the project SDK version in one place rather than in each individual project:
+
+```json
+{
+    "msbuild-sdks": {
+        "My.Custom.Sdk": "5.0.0",
+        "My.Other.Sdk": "1.0.0-beta"
+    }
+}
+```
+Only one version of each project SDK can be used during a build.  If you are referencing two different versions of the same project SDK, MSBuild will emit a warning.  It is recommended to **not** specify a version in your projects if a version is specified in your `global.json`.  
+
+## See Also  
+ [MSBuild Concepts](../msbuild/msbuild-concepts.md)   
+ [Customize Your Build](../msbuild/customize-your-build.md)   

docs/msbuild/project-element-msbuild.md

@@ -36,8 +36,10 @@ Required root element of an [!INCLUDE[vstecmsbuild](../extensibility/internals/i
 <Project InitialTargets="TargetA;TargetB"  
          DefaultTargets="TargetC;TargetD"  
          TreatAsLocalProperty="PropertyA;PropertyB"  
-         ToolsVersion=<version number>  
+         ToolsVersion=<version number>
+         Sdk="name[/version]"
          xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  
+    <Sdk... />
     <Choose>... </Choose>  
     <PropertyGroup>... </PropertyGroup>  
     <ItemGroup>... </ItemGroup>  
@@ -57,7 +59,7 @@ Required root element of an [!INCLUDE[vstecmsbuild](../extensibility/internals/i
 |---------------|-----------------|  
 |`DefaultTargets`|Optional attribute.<br /><br /> The default target or targets to be the entry point of the build if no target has been specified. Multiple targets are semi-colon (;) delimited.<br /><br /> If no default target is specified in either the `DefaultTargets` attribute or the [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] command line, the engine executes the first target in the project file after the [Import](../msbuild/import-element-msbuild.md) elements have been evaluated.|  
 |`InitialTargets`|Optional attribute.<br /><br /> The initial target or targets to be run before the targets specified in the `DefaultTargets` attribute or on the command line. Multiple targets are semi-colon (;) delimited.|  
-|`SDK`|Optional attribute. (Available only for .NET Core projects in Visual Studio 2017 or later.)<br /><br /> The SDK version to use to create implicit Import statements that are added to the .proj file. For example, `<Project Sdk="Microsoft.NET.Sdk/1.0.0-RC" />`.|  
+|`Sdk`|Optional attribute. <br /><br /> The SDK name and optional version to use to create implicit Import statements that are added to the .proj file. If no version is specified, MSBuild will attempt to resolve a default version.  For example, `<Project Sdk="Microsoft.NET.Sdk" />` or `<Project Sdk="My.Custom.Sdk/1.0.0" />`.|  
 |`ToolsVersion`|Optional attribute.<br /><br /> The version of the toolset MSBuild uses to determine the values for $(MSBuildBinPath) and $(MSBuildToolsPath).|  
 |`TreatAsLocalProperty`|Optional attribute.<br /><br /> Property names that won't be considered to be global. This attribute prevents specific command-line properties from overriding property values that are set in a project or targets file and all subsequent imports. Multiple properties are semi-colon (;) delimited.<br /><br /> Normally, global properties override property values that are set in the project or targets file. If the property is listed in the `TreatAsLocalProperty` value, the global property value doesn't override property values that are set in that file and any subsequent imports. For more information, see [How to: Build the Same Source Files with Different Options](../msbuild/how-to-build-the-same-source-files-with-different-options.md). **Note:**  You set global properties  at a command prompt by using the **/property** (or **/p**) switch. You can also set or modify global properties for child projects in a multi-project build by using the `Properties` attribute of the MSBuild task. For more information, see [MSBuild Task](../msbuild/msbuild-task.md).|  
 |`Xmlns`|Optional attribute.<br /><br /> When specified, the `xmlns` attribute must have the value of "http://schemas.microsoft.com/developer/msbuild/2003".|  
@@ -70,7 +72,8 @@ Required root element of an [!INCLUDE[vstecmsbuild](../extensibility/internals/i
 |[Import](../msbuild/import-element-msbuild.md)|Optional element.<br /><br /> Enables a project file to import another project file. There may be zero or more `Import` elements in a project.|  
 |[ItemGroup](../msbuild/itemgroup-element-msbuild.md)|Optional element.<br /><br /> A grouping element for individual items. Items are specified by using the [Item](../msbuild/item-element-msbuild.md) element. There may be zero or more `ItemGroup` elements in a project.|  
 |[ProjectExtensions](../msbuild/projectextensions-element-msbuild.md)|Optional element.<br /><br /> Provides a way to persist non-[!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] information in an [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] project file. There may be zero or one `ProjectExtensions` elements in a project.|  
-|[PropertyGroup](../msbuild/propertygroup-element-msbuild.md)|Optional element.<br /><br /> A grouping element for individual properties. Properties are specified by using the [Property](../msbuild/property-element-msbuild.md) element. There may be zero or more `PropertyGroup` elements in a project.|  
+|[PropertyGroup](../msbuild/propertygroup-element-msbuild.md)|Optional element.<br /><br /> A grouping element for individual properties. Properties are specified by using the [Property](../msbuild/property-element-msbuild.md) element. There may be zero or more `PropertyGroup` elements in a project.|
+|[Sdk](../msbuild/sdk-element-msbuild.md)|Optional element.<br /><br /> References an [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] project SDK.  This element can be used as an alternative to the Sdk attribute.|  
 |[Target](../msbuild/target-element-msbuild.md)|Optional element.<br /><br /> Contains a set of tasks for [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] to sequentially execute. Tasks are specified by using the [Task](../msbuild/task-element-msbuild.md) element. There may be zero or more `Target` elements in a project.|  
 |[UsingTask](../msbuild/usingtask-element-msbuild.md)|Optional element.<br /><br /> Provides a way to register tasks in [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)]. There may be zero or more `UsingTask` elements in a project.|  
 

docs/msbuild/sdk-element-msbuild.md

@@ -0,0 +1,62 @@
+---
+title: "Sdk Element (MSBuild) | Microsoft Docs"
+ms.custom: ""
+ms.date: "01/25/2018"
+ms.reviewer: ""
+ms.suite: ""
+ms.technology: 
+  - "vs-ide-sdk"
+ms.tgt_pltfrm: ""
+ms.topic: "article"
+f1_keywords: 
+  - "http://schemas.microsoft.com/developer/msbuild/2003#Project"
+dev_langs: 
+  - "VB"
+  - "CSharp"
+  - "C++"
+  - "jsharp"
+helpviewer_keywords: 
+  - "Sdk element [MSBuild]"
+  - "<Sdk> element [MSBuild]"
+author: "jeffkl"
+ms.author: "jeffkl"
+manager: angerlic
+ms.workload: 
+  - "multiple"
+---
+# Sdk Element (MSBuild)
+References an [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] project SDK.  
+
+ \<Project>  
+ \<Sdk>  
+
+
+## Syntax  
+
+```  
+<Sdk Name="My.Custom.Sdk"
+     Version="1.0.0" />  
+```  
+
+## Attributes and Elements  
+ The following sections describe attributes, child elements, and parent elements.  
+
+### Attributes  
+
+|Attribute|Description|  
+|---------------|-----------------|  
+|`Name`|Required attribute.<br /><br /> The name of the project SDK.|  
+|`Version`|Optional attribute.<br /><br /> The version of the project SDK|  
+
+### Child Elements  
+ None.
+
+### Parent Elements  
+ |Element|Description|  
+|-------------|-----------------|  
+|[Project](../msbuild/project-element-msbuild.md)|Required root element of an [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] project file.|  
+
+## See Also  
+ [How to: Reference an MSBuild Project SDK](../msbuild/how-to-use-project-sdk.md)   
+ [Project File Schema Reference](../msbuild/msbuild-project-file-schema-reference.md)   
+ [MSBuild](../msbuild/msbuild.md)