Add documentation for using MSBuild project SDKs by jeffkl · Pull Request #487 · MicrosoftDocs/visualstudio-docs

jeffkl · 2018-01-24T22:13:21Z

Fix casing of Sdk attribute in Project element reference and include an example

Also include an example

opbldsb2 · 2018-01-24T22:14:21Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs/msbuild/how-use-project-sdk.md	✅Succeeded
docs/msbuild/project-element-msbuild.md	✅Succeeded

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

jeffkl · 2018-01-24T22:14:36Z

Please review @AndyGerlicher and @rainersigwald

rainersigwald

@Mikejo5000 can you take a look too?

rainersigwald · 2018-01-24T22:17:16Z

 |`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, a default SDK will be looked for.  Example, `<Project Sdk="Microsoft.NET.Sdk" />` or `<Project Sdk="My.Custom.Sdk/1.0.0" />`.|  


a default SDK will be looked for doesn't read right to me. If no version is specified, the toolset will attempt to resolve a default version of that SDK, if it exists?

rainersigwald · 2018-01-24T22:19:31Z

+2. Use the `<Sdk/>` element for implicit imports:
+    ```xml
+    <Project>
+        <Sdk Name="Microsoft.NET.Sdk" Version="1.2.3" />


I think we should not use Microsoft.NET.Sdk for examples with versions, since we expect to not want people to specify versions for that. Make up an example SDK?

rainersigwald · 2018-01-24T22:20:02Z

+    ```
+    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 `Microsoft.NET.Sdk/1.2.3`.
+
+2. Use the `<Sdk/>` element for implicit imports:


Use the top-level Sdk element . . .

rainersigwald · 2018-01-24T22:20:50Z

+   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:


rainersigwald · 2018-01-24T22:27:30Z

+  - "MSBuild, SDKs"
+  - "MSBuild, overriding DependsOn properties"
+  - "MSBuild, extending Visual Studio builds"
+  - "MSBuild, DependsOn properties"


Probably not all of these?

rainersigwald · 2018-01-24T22:34:42Z

+  - "multiple"
+---
+# How to: Use MSBuild Project SDKs
+In [!INCLUDE[vstecmsbuild](../extensibility/internals/includes/vstecmsbuild_md.md)] 15.0 a new concept was introduced called project software development kits (SDKs). 


MSBuild 15.0 introduced the concept of the "project Sdk", which simplifies using software development kits that require properties and targets to be imported.

rainersigwald · 2018-01-24T22:35:14Z

+    ```
+    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 `Microsoft.NET.Sdk/1.2.3`.
+
+2. Use the `<Sdk/>` element for implicit imports:


We should also add the Sdk element in the schema documentation.

rainersigwald · 2018-01-24T22:35:37Z

+   This resolver is only active if you specified an optional version and 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 installed with MSBuild.


that were installed with msbuild

rainersigwald · 2018-01-24T22:37:00Z

+        "My.Other.Sdk": "1.0.0-beta"
+    }
+}
+```


After defining a version for an Sdk in global.json, reference it with no version in individual project files.

opbld10 · 2018-01-24T23:02:20Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs/msbuild/how-use-project-sdk.md	✅Succeeded
docs/msbuild/project-element-msbuild.md	✅Succeeded

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbld10 · 2018-01-24T23:12:25Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs/msbuild/how-to-use-project-sdk.md	✅Succeeded
docs/msbuild/project-element-msbuild.md	✅Succeeded
docs/msbuild/sdk-element-msbuild.md	✅Succeeded

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbld11 · 2018-01-25T16:31:47Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs/msbuild/how-to-use-project-sdk.md	✅Succeeded
docs/msbuild/project-element-msbuild.md	✅Succeeded
docs/msbuild/sdk-element-msbuild.md	✅Succeeded

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

Mikejo5000

@jeffkl @rainersigwald Jeff, Would you add nav links to the new topics in docs/extensibility/TOC.md? Thx!

opbldsb3 · 2018-01-25T17:05:37Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs/msbuild/TOC.md	✅Succeeded
docs/msbuild/how-to-use-project-sdk.md	✅Succeeded
docs/msbuild/project-element-msbuild.md	✅Succeeded
docs/msbuild/sdk-element-msbuild.md	✅Succeeded

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

jeffkl · 2018-01-25T17:06:11Z

@Mikejo5000 I didn't see any relevant sections in docs/extensibility/TOC.md but I did just update docs/msbuild/TOC.md, thanks for pointing that out. Do you have any other specific TOC areas you think I should update?

Mikejo5000 · 2018-01-25T17:29:17Z

@jeffkl docs/msbuild/TOC.md is the correct file. Thanks!

opbld13 · 2018-01-25T19:30:48Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs/msbuild/TOC.md	✅Succeeded
docs/msbuild/how-to-use-project-sdk.md	✅Succeeded
docs/msbuild/project-element-msbuild.md	✅Succeeded
docs/msbuild/sdk-element-msbuild.md	✅Succeeded

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

opbldsb9 · 2018-01-25T19:31:57Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs/msbuild/TOC.md	✅Succeeded
docs/msbuild/how-to-use-project-sdk.md	✅Succeeded
docs/msbuild/project-element-msbuild.md	✅Succeeded
docs/msbuild/sdk-element-msbuild.md	✅Succeeded

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

Mikejo5000

@jeffkl @rainersigwald Looks good. Made a few minor edits.

opbld10 · 2018-01-25T19:33:36Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs/msbuild/TOC.md	✅Succeeded
docs/msbuild/how-to-use-project-sdk.md	✅Succeeded
docs/msbuild/project-element-msbuild.md	✅Succeeded
docs/msbuild/sdk-element-msbuild.md	✅Succeeded

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

jeffkl added 2 commits January 24, 2018 14:11

Fix casing of Sdk attribute in Project element reference

f3cdca1

Also include an example

Add page documenting using project SDKs

a390d1a

jeffkl mentioned this pull request Jan 24, 2018

NuGet-based SDK resolver design spec dotnet/msbuild#2803

Closed

7 tasks

rainersigwald reviewed Jan 24, 2018

View reviewed changes

Address feedback

aa5c2d1

Add Sdk element documentation

9b1d4bd

Add references to Sdk element in Project element documentation

ccd6619

Mikejo5000 requested changes Jan 25, 2018

View reviewed changes

Mikejo5000 self-assigned this Jan 25, 2018

Add some links in MSBuild\TOC.md

152fd7b

A few minor edits

3bfe660

Minor edit

1192516

Metadata edits

ffb61a9

Mikejo5000 approved these changes Jan 25, 2018

View reviewed changes

Mikejo5000 merged commit 5290854 into MicrosoftDocs:master Jan 25, 2018

jeffkl deleted the sdks branch January 25, 2018 20:46

Conversation

jeffkl commented Jan 24, 2018

Uh oh!

opbldsb2 commented Jan 24, 2018

✅ Validation status: passed

Uh oh!

jeffkl commented Jan 24, 2018

Uh oh!

rainersigwald left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

opbld10 commented Jan 24, 2018

✅ Validation status: passed

Uh oh!

opbld10 commented Jan 24, 2018

✅ Validation status: passed

Uh oh!

opbld11 commented Jan 25, 2018

✅ Validation status: passed

Uh oh!

Mikejo5000 left a comment

Choose a reason for hiding this comment

Uh oh!

opbldsb3 commented Jan 25, 2018

✅ Validation status: passed

Uh oh!

jeffkl commented Jan 25, 2018

Uh oh!

Mikejo5000 commented Jan 25, 2018

Uh oh!

opbld13 commented Jan 25, 2018

✅ Validation status: passed

Uh oh!

opbldsb9 commented Jan 25, 2018

✅ Validation status: passed

Uh oh!

Mikejo5000 left a comment

Choose a reason for hiding this comment

Uh oh!

opbld10 commented Jan 25, 2018

✅ Validation status: passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants