Skip to content

UsingMSBuildSdks.md

Latest commit

 

History

History
64 lines (51 loc) · 3.85 KB

UsingMSBuildSdks.md

File metadata and controls

64 lines (51 loc) · 3.85 KB

Using MSBuild SDKs

Note

The following document uses Lombiq.MSBuild.OrchardCore.Module.Sdk as an example, but you can achieve the same with all of the Lombiq.MSBuild.OrchardCore.*.Sdk projects.

It can be used by updating your project XML's root Sdk attribute to contain the NuGet package name and version, like this:

<Project Sdk="Lombiq.MSBuild.OrchardCore.Module.Sdk/1.0.0">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  ...
</Project>

Or by removing the Sdk attribute and importing the .props and .targets files directly form the NuGet package. In this case the Sdk attribute of the import indicates where to look for the file in the NuGet package cache.

<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <Import Project="Sdk.props" Sdk="Lombiq.MSBuild.OrchardCore.Module.Sdk" Version="1.0.0" />
  ...
  <Import Project="Sdk.targets" Sdk="Lombiq.MSBuild.OrchardCore.Module.Sdk" Version="1.0.0" />
</Project>

If you want to use a local copy rather than NuGet, you can import these files by giving a full path, like with any other Targets project:

<Project>
  <Import Project="../../../Utilities/Lombiq.MSBuild.Targets/Lombiq.MSBuild.OrchardCore.Module.Sdk/Sdk/Import.props" />
  ...
  <Import Project="../../../Utilities/Lombiq.MSBuild.Targets/Lombiq.MSBuild.OrchardCore.Module.Sdk/Sdk/Import.targets" />
</Project>

Important

Make sure to import the Sdk.props and Sdk.targets files for NuGet, but the Import.props and Import.targets files for submodule. They both reference the same code files, but there are slight differences accounted in these different consumable files.

You can mix the latter two approaches if you need to support both NuGet and submodule use. We do this in our projects (for example here), because <Sdk Condition="..." Name="..."> is not supported by .NET, so the two cases can only be toggled using imports.

Common Features

All of our MSBuild SDK projects share these features and configurations:

  • Link and pack Readme.md and NuGetIcon.png files, if they exist.
  • Link and pack ../Readme.md as Readme.md if it doesn't exist in the project directory. This is useful for the primary project of a repository.
  • If the project has <IsLombiqProject>true</IsLombiqProject> property, then a lot of NuGet properties are provided with appropriate defaults to reduce boilerplate:
    • Authors: Defaults to Lombiq Technologies.
    • Copyright: Use the <CopyrightYear> property to make it Copyright © $(CopyrightYear), Lombiq Technologies Ltd..
    • Description: Use the <DescriptionBody> property to make it $(Title): $(DescriptionBody).
    • PackageIcon: Defaults to NuGetIcon.png if NuGetIcon.png exists.
    • PackageTags: Defaults to OrchardCore;Lombiq;AspNetCore.
    • PackageProjectUrl: Defaults to the value of <RepositoryUrl>, so you don't have to enter both if they are the same.
    • PackageLicenseExpression: Defaults to BSD-3-Clause.
  • When you import the SDK via the Import.props file, it tries to automatically set these values if they are not yet initialized:
    • LombiqSolutionRootPath: Path of the directory where the solution file and the src directory should be.
    • LombiqHelpfulLibrariesPath: Path of the src/Libraries/Lombiq.HelpfulLibraries directory where the Lombiq Helpful Libraries submodule should be.
    • LombiqAnalyzersPath: Path of the tools/Lombiq.Analyzers directory where the .NET Analyzers submodule should be.
  • If you import the SDK via the <Sdk> element or the Sdk.props file, it sets the <FromNuGet>true</FromNuGet> property.