Document the ProjectReference protocol #1892

rainersigwald · 2017-03-21T16:11:02Z

Wrote a document explaining what ProjectReferences do behind the scenes
and how to make a green-field project that doesn't import the machinery
of Common.targets compatibile with using them.

Wrote a document explaining what ProjectReferences do behind the scenes and how to make a green-field project that doesn't import the machinery of Common.targets compatibile with using them.

rainersigwald · 2017-03-21T16:15:45Z

@kempb, @nguerrera (this doesn't include the changes I'm making in a parallel PR but I plan to update it with that after the initial version goes in).

nguerrera · 2017-03-21T16:30:20Z

documentation/ProjectReference-Protocol.md

+
+As with all MSBuild logic, targets can be added to do other work with `ProjectReference`s.
+
+In particular, NuGet depends on being able to identify referenced projects' package dependencies, and calls some targets that are imported through `Microsoft.Common.targets` to do so. At the time of writing this this is in [`NuGet.targets`](https://github.com/NuGet/NuGet.Client/blob/79264a74262354c1a8f899c2c9ddcaff58afaf62/src/NuGet.Core/NuGet.Build.Tasks/NuGet.targets).


Along the same lines, xaml targets add extra GetPackagingOutputs requirement

Added that, thanks--there's probably a lot of these, unfortunately.

Sorry, I said Xaml, but I should have said Appx, Microsoft.AppxPackage.targets is the specific thing that adds this requirement.

nguerrera · 2017-03-21T16:32:11Z

documentation/ProjectReference-Protocol.md

+These targets should exist in a project to be compatible with the common targets' `ProjectReference`. Some are called only conditionally.
+
+These targets are all defined in `Microsoft.Common.targets` and are defined in Microsoft SDKs. You should only have to implement them yourself if you require custom behavior or are authoring a project that doesn't import the common targets.
+


Should we discuss how the targets after GetTargetFrameworkProperties need only be defined in the evaluation that includes the properties it returned? i.e. These aren't all defined in cross-targeting context, but that's OK.

Added language to that effect in the targets section, think it's clear enough?

nguerrera

Very nice.

nguerrera · 2017-03-21T17:06:39Z

documentation/ProjectReference-Protocol.md

@@ -52,6 +52,7 @@ These targets are all defined in `Microsoft.Common.targets` and are defined in M
  * **New** for MSBuild 15/Visual Studio 2017. Supports the cross-targeting feature allowing a project to have multiple `TargetFrameworks`.
  * **Conditions**: only when metadata `SkipGetTargetFrameworkProperties` for each reference is not true.
  * Skipped for `*.vcxproj` by default.
+  * This target must be present in a build request that does not specify a `TargetFramework`—the “outer” build. It is not required in a fully-specified (“inner”) build.


I was more concerned about the inverse: the ones below need to be in inner build, but not outer.

cdmihai · 2017-03-22T00:35:02Z

documentation/ProjectReference-Protocol.md

+</ItemGroup>
+```
+
+Including `Microsoft.Common.targets` includes logic that consumes these items and transforms them into compile-time references before the compiler runs. 


Importing ...

cdmihai · 2017-03-22T00:38:40Z

documentation/ProjectReference-Protocol.md

+
+`AssignProjectConfiguration` runs when building in a solution context, and ensures that the right `Configuration` and `Platform` are assigned to each reference. For example, if a solution specifies (using the Solution Build Manager) that for a given solution configuration, a project should always be built `Release`, that is applied inside MSBuild in this target.
+
+`PrepareProjectReferences` then runs, ensuring that each referenced project exists (creating the item `@(_MSBuildProjectReferenceExistent)`) and asking it for the closest matching `TargetFramework` to build.


and asking it for the closest matching TargetFramework to build.

I'd make a new paragraph out of that snippet, with more details :)

cdmihai · 2017-03-22T00:42:34Z

documentation/ProjectReference-Protocol.md

+
+These targets are all defined in `Microsoft.Common.targets` and are defined in Microsoft SDKs. You should only have to implement them yourself if you require custom behavior or are authoring a project that doesn't import the common targets.
+
+If implementing a project with an “outer” (determine what properties to pass to the real build) and “inner” (fully specified) build, only `GetTargetFrameworkProperties` is required in the “outer” build. The other targets listed can be “inner” build only.


I wanted to comment that linking some doc for outer and inner builds from the SDK repo would be nice, but I couldn't find any :(

Yeah, we should write one. Either next to this file or in the Sdk repo--it's kind of a core MSBuild concept now, but only really used in the Sdk, so I could see it going either way.

cdmihai · 2017-03-22T00:44:15Z

documentation/ProjectReference-Protocol.md

+<!--* `BuildGenerateSources` is run
+  * **Conditions**: only if `'$(BuildPassReferences)' == 'true'`.
+  * Rare in managed projects but common in C++ scenarios (for example, using IDL to generate header code).-->
+* `GetTargetFrameworkProperties` determines what properties should be passed to the main get-build-output target.


get-build-output target

Is that GetTargetPath? What do non-VS builds call?

It's GetTargetPath in VS, default target by default otherwise, but the default target can be overridden by the consumer by setting the metadata Targets on the ProjectReference.

rainersigwald · 2017-03-22T21:41:10Z

@dotnet-bot test Windows_NT Build for Desktop please

Document the ProjectReference protocol

c6b7556

Wrote a document explaining what ProjectReferences do behind the scenes and how to make a green-field project that doesn't import the machinery of Common.targets compatibile with using them.

dnfclas added the cla-already-signed label Mar 21, 2017

nguerrera reviewed Mar 21, 2017

View reviewed changes

nguerrera approved these changes Mar 21, 2017

View reviewed changes

rainersigwald added 2 commits March 21, 2017 11:36

Add mention of XAML

c4ec037

GetTargetFrameworkProperties can be outer-build

1939e1e

nguerrera reviewed Mar 21, 2017

View reviewed changes

rainersigwald added 2 commits March 21, 2017 12:07

Xaml->appx

61871b2

Clarify inner/outer reqs

a2414be

nguerrera approved these changes Mar 21, 2017

View reviewed changes

AndyGerlicher approved these changes Mar 21, 2017

View reviewed changes

cdmihai reviewed Mar 22, 2017

View reviewed changes

cdmihai approved these changes Mar 22, 2017

View reviewed changes

feedback from Mihai

96e466a

AndyGerlicher merged commit 14e2e82 into dotnet:master Mar 23, 2017

rainersigwald deleted the ProjectReference-protocol-doc branch April 11, 2017 20:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document the ProjectReference protocol #1892

Document the ProjectReference protocol #1892

rainersigwald commented Mar 21, 2017

rainersigwald commented Mar 21, 2017

nguerrera Mar 21, 2017 •

edited

Loading

rainersigwald Mar 21, 2017

nguerrera Mar 21, 2017

nguerrera Mar 21, 2017

rainersigwald Mar 21, 2017

nguerrera left a comment

nguerrera Mar 21, 2017

cdmihai Mar 22, 2017

cdmihai Mar 22, 2017 •

edited

Loading

cdmihai Mar 22, 2017

rainersigwald Mar 22, 2017

cdmihai Mar 22, 2017 •

edited

Loading

rainersigwald Mar 22, 2017

rainersigwald commented Mar 22, 2017


		As with all MSBuild logic, targets can be added to do other work with `ProjectReference`s.

		In particular, NuGet depends on being able to identify referenced projects' package dependencies, and calls some targets that are imported through `Microsoft.Common.targets` to do so. At the time of writing this this is in [`NuGet.targets`](https://github.com/NuGet/NuGet.Client/blob/79264a74262354c1a8f899c2c9ddcaff58afaf62/src/NuGet.Core/NuGet.Build.Tasks/NuGet.targets).

		These targets should exist in a project to be compatible with the common targets' `ProjectReference`. Some are called only conditionally.

		These targets are all defined in `Microsoft.Common.targets` and are defined in Microsoft SDKs. You should only have to implement them yourself if you require custom behavior or are authoring a project that doesn't import the common targets.


		`AssignProjectConfiguration` runs when building in a solution context, and ensures that the right `Configuration` and `Platform` are assigned to each reference. For example, if a solution specifies (using the Solution Build Manager) that for a given solution configuration, a project should always be built `Release`, that is applied inside MSBuild in this target.

		`PrepareProjectReferences` then runs, ensuring that each referenced project exists (creating the item `@(_MSBuildProjectReferenceExistent)`) and asking it for the closest matching `TargetFramework` to build.


		These targets are all defined in `Microsoft.Common.targets` and are defined in Microsoft SDKs. You should only have to implement them yourself if you require custom behavior or are authoring a project that doesn't import the common targets.

		If implementing a project with an “outer” (determine what properties to pass to the real build) and “inner” (fully specified) build, only `GetTargetFrameworkProperties` is required in the “outer” build. The other targets listed can be “inner” build only.

Document the ProjectReference protocol #1892

Document the ProjectReference protocol #1892

Conversation

rainersigwald commented Mar 21, 2017

rainersigwald commented Mar 21, 2017

nguerrera Mar 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nguerrera left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cdmihai Mar 22, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cdmihai Mar 22, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rainersigwald commented Mar 22, 2017

nguerrera Mar 21, 2017 •

edited

Loading

cdmihai Mar 22, 2017 •

edited

Loading

cdmihai Mar 22, 2017 •

edited

Loading