MSBuild is the powerful build system used in .NET. With .NET Core, it is now widely used cross-platform and has been open sourced. Since MSBuild has been powering .NET Core builds since 2017, it has unlocked remarkable possibilities that were not possible with project.json. It has a programming language of its own. This session introduces to this programming language, explains common build customization techniques, helps avoid pitfalls when setting up your custom build logic and explores strategies to investigate build errors.

1. MSBuild
> Martin Ullrich, @dasMulli

2. © CSS GmbH | 2016
About myself
Martin Ullrich - @dasMulli
 Software Engineer at CSS
– C#/.NET, iOS (ObjC/Swift), Java, Frontends, …
– Cares about Build Automation, CI / CD
 Somewhat active on .NET Core GitHub Repos
 Learned MSBuild in 2016
2

3. © CSS GmbH | 2016 3

4. © CSS GmbH | 2016
AGENDA
 Overview and Context
 How it works
 Diagnosing Issues
 Demos - Tips and Tricks
 Ask Me Anything
4

5. © CSS GmbH | 2016
GOALS
 Never use „xcopy“ in build events again
 Have an easier time navigating .csproj files
5

6. MSBuild
“The 2003 Format”
6

7. © CSS GmbH | 2016
project.json 😢
7
{
"version": "1.2.3",
"dependencies": {
"Newtonsoft.Json": "10.0.1"
},
"frameworks": {
"netcoreapp1.0": {
"dependencies": {
"Microsoft.NetCore.App": {
"type": "platform",
"version": "1.0.0"
}
}
}
}
}

8. © CSS GmbH | 2016
The Reality
8

9. © CSS GmbH | 2016
Why didn’t project.json save us all?
 .csproj too complicated back then
 Chicken or the egg problem
 How do I migrate 100 projects?
 .NET Standard projects need to be referenced by existing
projects.
 “.xproj”
– Visual Studio and existing tools are built around MSBuild
 Limited extensibility
9

10. © CSS GmbH | 2016
Other dotnet CLI issues
 Re-implemented many MSBuild features
– Incremental compilation
– Configuration management
 NuGet packages containing MSBuild logic no longer work
 Bugs
 Visual Studio: UI over project.json
 OmniSharp & others: separate handling
10

11. © CSS GmbH | 2016
Build Systems
11
DSL
”flexible”
Code
MSBuild
project.json
Gradle
Grunt
Gulp
Maven
Cake

12. © CSS GmbH | 2016
MSBuild 15
 Open Source 🎉 - https://github.com/Microsoft/msbuild
 Runs on .NET Core and Mono
– Replaces xbuild on Mono
 Syntactic sugar
– SDKs, Metadata Attributes for Items, …
 Automatically discovered files
– Directory.Build.(props|targets|rsp)
 Performance Improvements
 More Features & Functionality on each minor
release
12

13. © CSS GmbH | 2016
Tooling - IDEs
 Visual Studio
 OmniSharp
– Visual Studio Code
– Atom, Vim, …
 Visual Studio for Mac
 Rider
 3rd party tools
– E.g. dotnet-outdated
13

14. © CSS GmbH | 2016
Visual Studio: Project Systems
14
Source: https://github.com/dotnet/project-system

15. © CSS GmbH | 2016
Visual Studio: Project Systems
 csproj.dll, msvbproj.dll
– Native, COM-based
– Single-threaded, bound to UI Thread
– Super hard to extend
 “the new project system” – dotnet/project-system
– Managed
– Multi-threaded, scalable, responsive
– Easier to extend via MEF / managed code
– Parts of it are VS-independent
– Developed on GitHub
15

16. © CSS GmbH | 2016
MSBuild 101
 XML Format
 Definitions + Logic
– Can look like a DSL
 "Variables”, “Lists”
 Conditions, Loops  Control Flow
 Is it a programming language?
16

17. Hello MSBuild - Code
17

18. © CSS GmbH | 2016
Project Files
 Any XML file can be an MSBuild project
 .props / .targets are only a loose convention
– .props = Beginning of files / contain defaults
– .targets = End of files / build logic
 MSBuild command line looks for *.*proj files by default
18

19. © CSS GmbH | September 2014
Properties vs. Items
 Key-Value Pair
 “Variable”
 Single Value
 Environment Variables are
Properties
 Global Properties
– Can override definition in project
file
 Collections
 “Lists”
 Identity + Metadata
– Duplicates are possible
 May represent files on
disk
–  Glob Patterns
 Used for Batching
– “Loops”, “Group By”
 Item Definition
–  Default Metadata 19

20. © CSS GmbH | 2016
Properties
$(MyProperty)
20

21. © CSS GmbH | 2016
Items
@(MyItems)
 MyItemA;MyItemB
@(MyItems->’%(Identity).old’)
 MyItemA.old;MyItemB.old
@(Person->’%(LastName)’, ‘ - ‘)
 Ullrich – Doe
21

22. © CSS GmbH | 2016
Warning: Static Evaluation
 All project XML is scanned before targets run
– “Static Evaluation”
 Order is important here:
1. Properties and Imports
2. Item definitions
3. Items
 Allows for a few ”default item” features
– EnableDefaultItems
– EnableDefaultCompileItems
– …
22

23. © CSS GmbH | 2016
Property Functions
 MSBuild allows calling .NET code
– Built-In functions
– Some select .NET Types
<NewGuid>$([System.Guid]::NewGuid())</NewGuid>
<Sum>$([MSBuild]::Add($(CommitCount), 2))</Sum>
<IsBeta>$(Version.EndsWith(‘beta’))</IsBeta>
23

24. © CSS GmbH | 2016
Targets
 Contain actual build logic
 Contains tasks
– Property and Item Groups are “intrinsic tasks”
 Targets can have dependencies
–  Graph
 Targets can define Inputs and Outputs
– Enbales incremental builds (skipping targets)
– Newest timestamps of Inputs and Outputs are compared
24

25. © CSS GmbH | 2016
Project SDKs
 Automatic Imports
 SdkResolvers try to find the SDK
– Name or Name/Version
– On disk or NuGet
 “SdkSdk.props” and “SdkSdk.targets” will be imported
automatically
 Import tag also supports Sdk attribute
25

26. © CSS GmbH | 2016
Restore
 dotnet msbuild "-t:Restore;Build”
– Can fail due to XML caches
 dotnet msbuild -restore -t:Build
– Runs the “Restore” target before the actual build
– Clears all MSBuild caches in between
26

27. Diagnostics?
27

28. © CSS GmbH | 2016
So you just hit a build error
 Logs are your best friend
 Verbose logs: msbuild -flp:verbosity=diag
 Binary logs (15.3+): msbuild -bl
– Embeds project file contents
– Super helpful for looking at issues without the source
 Structured Log Viewer
– http://msbuildlog.com
28

29. Demo time
29

30. © CSS GmbH | 2016
Demo Menu
 Publish for multiple target frameworks
 Using ”MSBuild Scripts” for your CI pipeline
 1 Directory, multiple SDK-style csproj files
 Include referenced Projects in NuGet package
 Ship your build logic as NuGet packages
– + Create your own “Project SDK”
 Create inline MSBuild Tasks with RolsynCodeTaskFactory
 Creating a cross-platform MSBuild Task
30

31. Questions
31

32. © CSS GmbH | 2016
Frequent Questions
 What about Pre-/Post-build events in SDK projects?
 How do I enable binding redirects generation?
– Why do I need them for .NET Standard libraries?
 Why does my project have so many dependencies?
 .NET Core 2.1 shared fx roll-forward.
– a.k.a. <TargetLatestRuntimePatch>
 Where do I get help with severe build errors?
32

33. © CSS GmbH | 2016
Some Links
https://github.com/Microsoft/msbuild
https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild
https://github.com/dotnet/sdk
https://github.com/aspnet/websdk
https://docs.microsoft.com/en-us/dotnet/core/tools/csproj
33