Skip to content

useful-resources.md

Latest commit

 

History

History
50 lines (42 loc) · 10 KB

useful-resources.md

File metadata and controls

50 lines (42 loc) · 10 KB
Raw

🔗 Useful Resources

Articles, source code, tools and reference material collected here as a convenient and consolidated reference for anyone looking to author custom MSBuild project SDKs from scratch, extend an existing one or simply wanting to understand how it all works under the hood.

MSBuild Project SDK Authoring & Resolution

  • Use MSBuild project SDKs - Different ways to reference an MSBuild project SDK in a project file and how MSBuild resolves them at evaluation time.
  • MSBuild Project File Schema Reference - Reference for MSBuild project file schema, including all available XML elements, attributes and their meanings, with examples of how to use them in practice.
  • MSBuild SdkResolver - Documentation on how MSBuild resolves SDK references, including the role of SdkResolver assemblies, how to write a custom resolver and how to troubleshoot resolution issues.
  • .NET project SDKs - Overview of Microsoft .NET project SDKs covering available SDK types, project file structure, default file includes/excludes, implicit using directives, implicit package references, build events and build customization options.

Custom MSBuild Project SDK Examples

See Acknowledgments for context on these resources.

Selected Microsoft SDK Source Code

  • Microsoft.NET.Sdk - Source code for the core MSBuild tasks and targets that power the .NET SDK build process, handling everything from resolving NuGet package assets and framework references to generating runtime configuration files, app hosts and dependency context files.
  • Microsoft.NET.Sdk.Web - The src/WebSdk folder in the dotnet/sdk repository contains the MSBuild tasks, targets and packages that power building and publishing ASP.NET Core web apps, organized into three key components: Microsoft.NET.Sdk.Web.ProjectSystem (default globs and project capabilities), Microsoft.NET.Sdk.Publish (folder, MSDeploy, Zip and One Deploy publishing) and Microsoft.NET.Sdk.Web (a meta-package tying the two together).
  • Microsoft.Build.NoTargets - An MSBuild project SDK that allows project tree owners the ability to define projects that do not compile an assembly. This can be useful for utility projects that just copy files, build packages or any other function where an assembly is not compiled.

MSBuild Property References

  • Common MSBuild project properties - Reference for common MSBuild project properties that are frequently used in SDKs, including TargetFramework, OutputType, PackageReference and more, with explanations of their purpose and how they affect the build process.
  • C# compiler options - Comprehensive reference for all C# compiler options that can be set via MSBuild properties, including code generation, diagnostics, optimizations and more.
  • MSBuild reference for .NET SDK projects - Documents the MSBuild properties and items specific to the .NET SDK for configuring .NET projects.
  • ASP.NET Core Web SDK - What Microsoft.NET.Sdk.Web is, how to reference it in a project file and the features it enables, including implicit references to the ASP.NET Core shared framework, built-in analyzers and MSBuild targets for publish profiles and WebDeploy.
  • .NET SDK and CLI environment variables - Environment variables that can be used to configure the .NET SDK and CLI behavior, including how to specify custom MSBuild SDK versions and how to enable detailed logging for debugging purposes.
  • Artifacts output layout - In .NET 8 and later versions, there's an option to simplify the output path and folder structure for build outputs. All build outputs from all projects are gathered into a common location, separated by project. A common location makes it easy for tooling to anticipate where to find the outputs.

NuGet MSBuild Property References

  • NuGet pack and restore as MSBuild targets - Reference for the MSBuild targets that power NuGet package restore and packing, including Restore, Pack and Push, with explanations of how to use them in custom SDKs and how to troubleshoot common issues.
  • Auditing package dependencies for security vulnerabilities - Documentation on how to use the dotnet list package --vulnerable command to audit project dependencies for known security vulnerabilities and how to interpret the results to keep your projects secure.
  • Package validation - Overview of .NET API compatibility and package validation, including how to use the dotnet api command to analyze API changes, how to interpret compatibility reports and how to ensure your SDKs maintain strong compatibility guarantees.
  • SBOM Generation for .NET Projects - MSBuild task that generates an SBOM using the SBOM API and CLI tool. The MSBuild task binaries along with the associated targets are packaged as a NuGet package and can be consumed within a .NET project. Once installed, an SBOM will automatically be generated upon packing the .NET project.

Debugging MSBuild SDK Resolution

  • MSBuild Command-Line Reference - Reference for MSBuild command-line options, including how to query property values without running a full build and how to generate binary logs for deeper inspection.
  • Evaluate Items and Properties and Display Results of Targets - Documentation on how to evaluate MSBuild items and properties at different stages of the build process, including using the -getProperty and -getItem command-line switches to inspect resolved values without running a full build.
  • MSBuild Structured Log Viewer - Tool that captures and visualizes MSBuild logs in a structured, searchable tree format, making it far easier to diagnose and understand what MSBuild is doing during a build.
  • MSBuild Structured Log Viewer Wiki - Wiki documentation for the MSBuild Structured Log Viewer, providing tips, tricks and detailed explanations on how to use the tool effectively.
  • MSBuild Tips & Tricks - A collection of tips and tricks for working with MSBuild, including how to debug MSBuild issues, how to write custom tasks and targets and how to optimize build performance.

Analyzers

  • Meziantou.Analyzer - A Roslyn analyzer to enforce some good practices in C# in terms of design, usage, security, performance and style.
  • Microsoft.CodeAnalysis.BannedApiAnalyzers - A set of Roslyn analyzers that allow you to ban specific APIs from being used in your codebase, either by specifying them directly or by referencing an external configuration file. Useful for enforcing architectural boundaries, preventing usage of dangerous or deprecated APIs and maintaining a clean and consistent codebase.

Miscellaneous

  • global.json Overview - Documentation on how to use global.json to specify .NET and MSBuild SDK versions for consistent tooling across environments.
  • Central Package Management (CPM) - A NuGet feature that allows you to centralize and manage package versions in a single Directory.Packages.props file, reducing versioning friction and ensuring consistency across projects.
  • Customize the build by folder - MSBuild allows you to customize the build process for all projects in a directory by placing Directory.Build.props and Directory.Build.targets files in that directory. This is a powerful way to apply common configuration across multiple projects without needing to reference a custom SDK, though it operates at a different level of the build process and has different use cases compared to project SDKs.
  • Semantic Versioning - A specification for versioning software in a consistent and predictable manner. NuGet.org enforces SemVer compliance for publicly published packages and this repository follows the same convention regardless of feed.