- It returns an item with the following metadata:
- TargetFrameworks indicating what TargetFrameworks are available in the project
- TargetFrameworkMonikers and TargetPlatformMonikers indicating what framework / platform the TargetFrameworks map to. This is to support implicitly setting the target platform version (for example inferring that net5.0-windows means the same as net5.0-windows7.0 ) as well as treating the TargetFramework values as aliases
- Boolean metadata for HasSingleTargetFramework and IsRidAgnostic .
- Platforms indicating what platforms are available for the project to build as, and boolean metadata IsVcxOrNativeProj (used for SetPlatform Negotiation)
- Deprecated in MSBuild 15.5.
- 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 should return either
- a string of the form TargetFramework=$(NearestTargetFramework);ProjectHasSingleTargetFramework=$(_HasSingleTargetFramework);ProjectIsRidAgnostic=$(_IsRidAgnostic) , where the value of NearestTargetFramework will be used to formulate TargetFramework for the following calls and the other two properties are booleans, or
- an item with metadata DesiredTargetFrameworkProperties (key-value pairs of the form TargetFramework=net46 ), HasSingleTargetFramework (boolean), and IsRidAgnostic (boolean).
- Conditions: this is used for builds inside Visual Studio, but not on the command line.
- It's also used when the property BuildProjectReferences is false , manually indicating that all ProjectReferences are up to date and shouldn't be (re)built.
- This should return a single item that is the primary output of the project, with metadata describing that output. See TargetPathWithTargetPlatformMoniker for the default metadata.
- Conditions: this is not called when building inside Visual Studio. Instead, Visual Studio builds each project in isolation but in order, so the path returned from GetTargetPath can be assumed to exist at consumption time.
- If the ProjectReference defines the Targets metadata, it is used. If not, no target is passed, and the default target of the reference (usually Build ) is built.
- The return value of this target should be identical to that of GetTargetPath .
- As of 15.7, this is optional. If a project does not contain a GetNativeManifest target, it will not be referencable by native projects but will not fail the build.
- As of 15.7, this is optional. If a project does not contain a GetCopyToOutputDirectoryItems target, projects that reference it will not copy any of its outputs to their own output folders, but the build can succeed.
- It is not called during a normal build, only during "Clean" and "Rebuild".
Targets Marked With SkipNonexistentTargets='true' Metadatum
GetTargetFrameworks and GetTargetFrameworksWithPlatformForSingleTargetFramework are skippable if nonexistent since some project types (for example, wixproj projects) may not define them. See this comment for more details.
Other protocol requirements
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 .
Microsoft.AppxPackage.targets adds a dependency on the target GetPackagingOutputs .
Getting additional properties from referenced projects
As of MSBuild 16.10, it is possible to gather additional properties from referenced projects. To do this, the referenced project should declare an AdditionalTargetFrameworkInfoProperty item for each property that should be gathered for referencing projects. For example:
ItemGroup> AdditionalTargetFrameworkInfoProperty Include="SelfContained"/> AdditionalTargetFrameworkInfoProperty Include="_IsExecutable"/> ItemGroup>
These properties will then be gathered via the GetTargetFrameworks call. They will be available to the referencing project via the AdditionalPropertiesFromProject metadata on the _MSBuildProjectReferenceExistent item. The AdditionalPropertiesFromProject value will be an XML string which contains the values of the properties for each TargetFramework in the referenced project. For example:
⚠️ This format is being changed. Soon, the schema will replace with . You can opt into that behavior early by setting the _UseAttributeForTargetFrameworkInfoPropertyNames property to true. This property will have no effect after the transition is complete.
AdditionalProjectProperties> net5.0> SelfContained>trueSelfContained> _IsExecutable>true_IsExecutable> net5.0> net5.0-windows> SelfContained>falseSelfContained> _IsExecutable>true_IsExecutable> net5.0-windows> AdditionalProjectProperties>
The NearestTargetFramework metadata will be the target framework which was selected as the best one to use for the reference (via GetReferenceNearestTargetFrameworkTask ). This can be used to select which set of properties were used in the target framework that was active for the reference.
SetPlatform Negotiation
As of version 17.0, MSBuild can now dynamically figure out what platform a ProjectReference should build as. This includes a new target and task to determine what the SetPlatform metadata should be, or whether to undefine the platform so the referenced project builds with its default platform.
- _GetProjectReferenceTargetFrameworkProperties target performs the majority of the work for assigning SetPlatform metadata to project references.
- Calls the GetCompatiblePlatform task, which is responsible for negotiating between the current project's platform and the platforms of the referenced project to assign a NearestPlatform metadata to the item.
- Sets or undefines SetPlatform based on the NearestPlatform assignment from GetCompatiblePlatform
- This target explicitly runs after _GetProjectReferenceTargetFrameworkProperties because it needs to use the IsVcxOrNativeProj and Platforms properties returned by the GetTargetFrameworks call.
Note: If a ProjectReference has SetPlatform metadata defined already, the negotiation logic is skipped over.
Impact on the build
In addition to the above task and target, .vcxproj and .nativeproj projects will receive an extra MSBuild call to the GetTargetFrameworks target. Previously, TargetFramework negotiation skipped over these projects because they could not multi-target in the first place. Because SetPlatform negotiation needs information given from the GetTargetFrameworks target, it is required that the _GetProjectReferenceTargetFrameworkProperties target calls the MSBuild task on the ProjectReference.
This means most projects will see an evaluation with no global properties defined, unless set by the user.
How To Opt In
First, set the property EnableDynamicPlatformResolution to true for every project in your solution. The easiest way to do this is by creating a Directory.Build.props file and placing it at the root of your project directory:
Project> PropertyGroup> EnableDynamicPlatformResolution>trueEnableDynamicPlatformResolution> PropertyGroup> Project>
If only set in one project, the SetPlatform metadata will carry forward to every consecutive project reference.
Next, every referenced project is required to define a Platforms property, where Platforms is a semicolon-delimited list of platforms that project could build as. For .vcxproj or .nativeproj projects, Platforms is constructed from the ProjectConfiguration items that already exist in the project. For managed SDK projects, the default is AnyCPU . Managed non-SDK projects need to define this manually.
Lastly, a PlatformLookupTable may need to be defined for more complex scenarios. A PlatformLookupTable is a semicolon-delimited list of mappings between platforms.
Win32=x86 , for example. This means that when the current project is building as Win32 , it will attempt to build the referenced project as x86. This property is required when a managed AnyCPU project references an unmanaged project because AnyCPU does not directly map to an architecture-specific platform. You can define the table in two ways:- A standard property within the current project, in a Directory.Build.props/targets
- Metadata on the ProjectReference item. This option takes priority over the first to allow customizations per ProjectReference .
References between managed and unmanaged projects
Some cases of ProjectReference s require a $(PlatformLookupTable) to correctly determine what a referenced project should build as. References between managed and unmanaged projects also get a default lookup table that can be opted out of by setting the property UseDefaultPlatformLookupTables to false. See the table below for details.
Note: Defining a PlatformLookupTable overrides the default mapping.
Project Reference Type PlatformLookupTable Required? Notes Unmanaged -> Unmanaged No Managed -> Managed No Unmanaged -> Managed Optional Uses default mapping: Win32=x86 Managed -> Unmanaged Yes when the project is AnyCPU Uses default mapping: x86=Win32 Example: Project A: Managed, building as AnyCPU , has a ProjectReference on Project B. Project B: Unmanaged, has $(Platforms) constructed from its Platform metadata from its ProjectConfiguration items, defined as x64;Win32 .
Because AnyCPU does not map to anything architecture-specific, a custom mapping must be defined. Project A can either:
- Define PlatformLookupTable in its project or a Directory.Build.props as AnyCPU=x64 or AnyCPU=Win32 .
- Define PlatformLookupTable as metadata on the ProjectReference item, which would take priority over a lookup table defined elsewhere.
- When only one mapping is valid, you could also directly define SetPlatform metadata as Platform=foo . This would skip over most negotiation logic.
Example of project A defining a lookup table directly on the ProjectReference :
ItemGroup> ProjectReference Include="B.csproj" PlatformLookupTable="AnyCPU=Win32"> ItemGroup>
