Add documentation for using MSBuild project SDKs #487
Conversation
✅ Validation status: passed
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. |
|
Please review @AndyGerlicher and @rainersigwald |
| @@ -57,7 +58,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, a default SDK will be looked for. Example, `<Project Sdk="Microsoft.NET.Sdk" />` or `<Project Sdk="My.Custom.Sdk/1.0.0" />`.| | |||
There was a problem hiding this comment.
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?
docs/msbuild/how-use-project-sdk.md
Outdated
| 2. Use the `<Sdk/>` element for implicit imports: | ||
| ```xml | ||
| <Project> | ||
| <Sdk Name="Microsoft.NET.Sdk" Version="1.2.3" /> |
There was a problem hiding this comment.
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?
docs/msbuild/how-use-project-sdk.md
Outdated
| ``` | ||
| 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: |
There was a problem hiding this comment.
Use the top-level Sdk element . . .
docs/msbuild/how-use-project-sdk.md
Outdated
| 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: |
docs/msbuild/how-use-project-sdk.md
Outdated
| - "MSBuild, SDKs" | ||
| - "MSBuild, overriding DependsOn properties" | ||
| - "MSBuild, extending Visual Studio builds" | ||
| - "MSBuild, DependsOn properties" |
There was a problem hiding this comment.
Probably not all of these?
docs/msbuild/how-use-project-sdk.md
Outdated
| - "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). |
There was a problem hiding this comment.
MSBuild 15.0 introduced the concept of the "project Sdk", which simplifies using software development kits that require properties and targets to be imported.
docs/msbuild/how-use-project-sdk.md
Outdated
| ``` | ||
| 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: |
There was a problem hiding this comment.
We should also add the Sdk element in the schema documentation.
docs/msbuild/how-use-project-sdk.md
Outdated
| 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. |
There was a problem hiding this comment.
that were installed with msbuild
docs/msbuild/how-use-project-sdk.md
Outdated
| "My.Other.Sdk": "1.0.0-beta" | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
After defining a version for an Sdk in
global.json, reference it with no version in individual project files.
✅ Validation status: passed
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. |
✅ Validation status: passed
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. |
✅ Validation status: passed
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. |
There was a problem hiding this comment.
@jeffkl @rainersigwald Jeff, Would you add nav links to the new topics in docs/extensibility/TOC.md? Thx!
✅ Validation status: passed
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 I didn't see any relevant sections in |
|
@jeffkl docs/msbuild/TOC.md is the correct file. Thanks! |
✅ Validation status: passed
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. |
✅ Validation status: passed
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. |
✅ Validation status: passed
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. |
Fix casing of Sdk attribute in Project element reference and include an example