Edit

Share via

ResolveAssemblyReference task

Determines all assemblies that depend on the specified assemblies, including second and nth-order dependencies. See also Troubleshoot build errors with assembly references.

Parameters

The following table describes the parameters of the ResolveAssemblyReference task.

Parameter Description
AllowedAssemblyExtensions Optional String[] parameter.

The assembly file name extensions to use when resolving references. The default file name extensions are exe and dll.
AllowedRelatedFileExtensions Optional String[] parameter.

The file name extensions to use for a search for files that are related to one another. The default extensions are pdb and xml.
AppConfigFile Optional String parameter.

Specifies an app.config file from which to parse and extract bindingRedirect mappings. If this parameter is specified, the AutoUnify parameter must be false.
Assemblies Optional ITaskItem[] parameter.

Specifies the items for which full paths and dependencies must be identified. These items can have either simple names like "System" or strong names like "System, Version=2.0.3500.0, Culture=neutral, PublicKeyToken=b77a5c561934e089".

Items passed to this parameter may optionally have the following item metadata:

- Private: Boolean value. If true, then the item is copied locally. The default value is true.
- HintPath: String value. Specifies the path and file name to use as a reference. This metadata is used when {HintPathFromItem} is specified in the SearchPaths parameter. The default value is an empty string.
- SpecificVersion: Boolean value. If true, then the exact name specified in the Include attribute must match. If false, then any assembly with the same simple name works. If SpecificVersion isn't specified, then the task examines the value in the Include attribute of the item. If the attribute is a simple name, it behaves as if SpecificVersion was false. If the attribute is a strong name, it behaves as if SpecificVersion was true.
When used with a Reference item type, the Include attribute needs to be the full fusion name of the assembly to be resolved. The assembly is only resolved if fusion exactly matches the Include attribute.
When a project targets a .NET Framework version and references an assembly compiled for a higher .NET Framework version, the reference resolves only if it has SpecificVersion set to true.
When a project targets a profile and references an assembly that isn't in the profile, the reference resolves only if it has SpecificVersion set to true.
- ExecutableExtension: String value. When present, the resolved assembly must have this extension. When absent, dll is considered first, followed by .exe, for each examined directory.
- SubType: String value. Only items with empty SubType metadata is resolved into full assembly paths. Items with nonempty SubType metadata are ignored.
- AssemblyFolderKey: String value. This metadata is supported for legacy purposes. It specifies a user-defined registry key, such as hklm\<VendorFolder>, that Assemblies should use to resolve assembly references.
AssemblyFiles Optional ITaskItem[] parameter.

Specifies a list of fully qualified assemblies for which to find dependencies.

Items passed to this parameter may optionally have the following item metadata:

- Private: an optional Boolean value. If true, the item is copied locally.
- FusionName: optional String metadata. Specifies the simple or strong name for this item. If this attribute is present, it can save time because the assembly file doesn't have to be opened to get the name.
AssemblyInformationCacheOutputPath Optional String parameter.

If not null, serializes machine-agnostic information about AssemblyFiles inputs to the named file. This setting overrides the usual cache, so only use this setting if you're building an SDK with many references and intend to ship the cache to your customers.
AssemblyInformationCachePaths Optional ITaskItem parameter.

If not null, uses this set of caches as inputs if MSBuild can't find the usual cache in the obj folder. Typically provided by an SDK to improve first-build performance.
AutoUnify Optional Boolean parameter.

This parameter is used for building assemblies, such as DLLs, which can't have a normal App.Config file.

When true, the resulting dependency graph is automatically treated as if there were an App.Config file passed in to the AppConfigFile parameter. This virtual App.Config file has a bindingRedirect entry for each conflicting set of assemblies such that the highest version assembly is chosen. A consequence of this is that there will never be a warning about conflicting assemblies, because every conflict will have been resolved.

When true, each distinct remapping results in a high priority comment showing the old and new versions and that AutoUnify was true.

When true, the AppConfigFile parameter must be empty.

When false, no assembly version remapping will occur automatically. When two versions of an assembly are present, a warning is issued.

When false, each distinct conflict between different versions of the same assembly results in a high-priority comment. These comments are followed by a single warning. The warning has a unique error code and contains text that reads "Found conflicts between different versions of reference and dependent assemblies."

The default value is false.
CandidateAssemblyFiles Optional String[] parameter.

Specifies a list of assemblies to use for the search and resolution process. Values passed to this parameter must be absolute file names or project-relative file names.

Assemblies in this list are considered when the SearchPaths parameter contains {CandidateAssemblyFiles} as one of the paths to consider.
CopyLocalDependenciesWhenParentReferenceInGac Optional Boolean parameter.

If true, to determine if a dependency should be copied locally, one of the checks done is to see if the parent reference in the project file has the Private metadata set. If set, then the Private value is used as a dependency.

If the metadata isn't set, then the dependency goes through the same checks as the parent reference. One of these checks is to see if the reference is in the GAC. If a reference is in the GAC, then it isn't copied locally, because it's assumed to be in the GAC on the target machine. This only applies to a specific reference and not its dependencies.

For example, a reference in the project file that is in the GAC isn't copied locally, but its dependencies are copied locally because they aren't in the GAC.

If false, project file references are checked to see if they're in the GAC, and are copied locally as appropriate.

Dependencies are checked to see if they're in the GAC and are also checked to see if the parent reference from the project file is in the GAC.

If the parent reference from the project file is in the GAC, the dependency isn't copied locally.

Whether this parameter is true or false, if there are multiple parent references and any of them aren't in the GAC, then all of them are copied locally.
CopyLocalFiles Optional ITaskItem[] read-only output parameter.

Returns every file in the ResolvedFiles, ResolvedDependencyFiles, RelatedFiles, SatelliteFiles, and ScatterFiles parameters that has CopyLocal item metadata with a value of true.
DependsOnNETStandard Boolean output parameter.

Whether any of the resolved primary references depends on .NET Standard.
DependsOnSystemRuntime Boolean output parameter.

Whether any of the resolved primary references depends on System.Runtime.
DoNotCopyLocalIfInGac Optional Boolean parameter.

Enables legacy mode for CopyLocal determination. If true, referenced assemblies won't be copied locally if they're found in the GAC. If false, assemblies are copied locally unless they were found only in the GAC. The default value is false.
FilesWritten Optional ITaskItem[] output parameter.

Contains the items written to disk.
FindDependencies Optional Boolean parameter.

If true, dependencies are found. Otherwise, only primary references are found. The default value is true.
FindDependenciesOfExternallyResolvedReferences Optional Boolean parameter.

Force dependencies to be walked even when a reference is marked with ExternallyResolved=true metadata.
FindRelatedFiles Optional Boolean parameter.

If true, related files such as pdb files and xml files are found. The default value is true.
FindSatellites Optional Boolean parameter.

If true, satellite assemblies are found. The default value is true.
FindSerializationAssemblies Optional Boolean parameter.

If true, then the task searches for serialization assemblies. The default value is true.
FullFrameworkAssemblyTables Optional ITaskItem[] parameter.

Specifies items that have FrameworkDirectory metadata to associate a redist list with a particular framework directory. If the association isn't made, an error is logged. The resolve assembly reference (RAR) logic uses the target framework directory if a FrameworkDirectory isn't set.
FullFrameworkFolders Optional System.String[] parameter.

Specifies the folders that contain a RedistList directory. This directory represents the full framework for a given client profile, for example, %programfiles%\reference assemblies\microsoft\framework\v4.0.
FullTargetFrameworkSubsetNames Optional String[] parameter.

Contains a list of target framework subset names. If a subset name in the list matches one in the TargetFrameworkSubset name property, then the system excludes that particular target framework subset at build time.
IgnoreDefaultInstalledAssemblyTables Optional Boolean parameter.

If true, then the task searches for and uses additional installed assembly tables (or, "Redist Lists") that are found in the \RedistList directory under TargetFrameworkDirectories. The default value is false.
IgnoreDefaultInstalledAssemblySubsetTables Optional Boolean parameter.

If true, then the task searches for and uses additional installed assembly subset tables (or, "Subset Lists") that are found in the \SubsetList directory under TargetFrameworkDirectories. The default value is false.
IgnoreTargetFrameworkAttributeVersionMismatch Optional Boolean parameter.

If true, then the task resolves assemblies that target a higher .NET Framework version than the current project. The default value is false, which skips those references.
IgnoreVersionForFrameworkReferences Optional Boolean parameter.

If the primary reference is a framework assembly, ignore its version information and actually resolve the framework assembly from the currently targeted framework.
InstalledAssemblySubsetTables Optional ITaskItem[] parameter.

Contains a list of XML files that specify the assemblies that are expected to be in the target subset.

As an option, items in this list can specify the FrameworkDirectory metadata to associate an InstalledAssemblySubsetTable

with a particular framework directory.

If there's only one TargetFrameworkDirectories element, then any items in this list that lack the FrameworkDirectory" metadata are treated as though they're set to the unique value that is passed to TargetFrameworkDirectories.
InstalledAssemblyTables Optional String parameter.

Contains a list of XML files that specify the assemblies that are expected to be installed on the target computer.

When InstalledAssemblyTables is set, earlier versions of the assemblies in the list are merged into the newer versions that are listed in the XML. Also, assemblies that have a setting of InGAC='true' are considered prerequisites and are set to CopyLocal='false' unless explicitly overridden.

As an option, items in this list can specify FrameworkDirectory metadata to associate an InstalledAssemblyTable with a particular framework directory. However, this setting is ignored unless the Redist name begins with

Microsoft-Windows-CLRCoreComp.

If there's only one TargetFrameworkDirectories element, then any items in this list that lack the FrameworkDirectory metadata are treated as if they're set to the unique value that is passed

to TargetFrameworkDirectories.
LatestTargetFrameworkDirectories Optional String[] parameter.

Specifies a list of directories that contain the redist lists for the most current framework that can be targeted on the machine. If this isn't set, then the highest framework installed on the machine for a given target framework identifier is used.
OutputUnresolvedAssemblyConflicts Optional Boolean parameter.

If true, outputs any unresolved assembly conflicts with diagnostic code MSB3277 into the output UnresolveAssemblyConflicts.
ProfileName Optional String parameter.

Specifies the name of the framework profile to be targeted. For example, Client, Web, or Network. Relevant only to .NET Framework profiles.
RelatedFiles Optional ITaskItem[] read-only output parameter.

Contains related files, such as XML and pdb files that have the same base name as a reference.

The files listed in this parameter may optionally contain the following item metadata:

- Primary: Boolean value. If true, then the file item was passed into the array by using the Assemblies parameter. Default value is false.
- CopyLocal: Boolean value. Indicates whether the given reference should be copied to the output directory.
ResolvedDependencyFiles Optional ITaskItem[] read-only output parameter.

Contains the nth order paths to dependencies. This parameter doesn't include first order primary references, which are contained in the ResolvedFiles parameter.

The items in this parameter optionally contain the following item metadata:

- CopyLocal: Boolean value. Indicates whether the given reference should be copied to the output directory.
- FusionName: String value. Specifies the name for this dependency.
- ResolvedFrom: String value. Specifies the literal search path that this file was resolved from.
ResolvedFiles Optional ITaskItem[] read-only output parameter.

Contains a list of all primary references resolved to full paths.

The items in this parameter optionally contain the following item metadata:

- CopyLocal: Boolean value. Indicates whether the given reference should be copied to the output directory.
- FusionName: String value. Specifies the name for this dependency.
- ResolvedFrom: String value. Specifies the literal search path that this file was resolved from.
ResolvedSDKReferences Optional ITaskItem[] parameter.

A list of resolved SDK references, which contain the SDK name, SDK location, and the targeted configuration. These locations are only searched if the reference has the SDKName metadata attached to it.
SatelliteFiles Optional ITaskItem[] read-only output parameter.

Specifies any satellite files found. These files are CopyLocal=true if the reference or dependency that caused this item to exist is CopyLocal=true.

The items in this parameter optionally contain the following item metadata:

- CopyLocal: Boolean value. Indicates whether the given reference should be copied to the output directory. This value is true if the reference or dependency that caused this item to exist has a CopyLocal value of true.
- DestinationSubDirectory: String value. Specifies the relative destination directory to copy this item to.
ScatterFiles Optional ITaskItem[] read-only output parameter.

Contains the scatter files associated with one of the given assemblies.

The items in this parameter optionally contain the following item metadata:

- CopyLocal: Boolean value. Indicates whether the given reference should be copied to the output directory.
SearchPaths Required String[] parameter.

Specifies the directories or special locations that are searched to find the files on disk that represent the assemblies. The order in which the search paths are listed is important. For each assembly, the list of paths is searched from left to right. When a file that represents the assembly is found, that search stops and the search for the next assembly starts.

This parameter accepts a semicolon-delimited list of values that can be either directory paths or special literal values from the list below:

- {HintPathFromItem}: Instructs the task to examine the HintPath metadata of the base item.
- {CandidateAssemblyFiles}: Instructs the task to examine the files passed in through the CandidateAssemblyFiles parameter.
- {Registry: <AssemblyFoldersBase>, <RuntimeVersion>, <AssemblyFoldersSuffix>}: Instructs the task to search in additional folders specified in the registry. <AssemblyFoldersBase>, <RuntimeVersion>, and <AssemblyFoldersSuffix> should be replaced with specific values for the registry location to be searched. The default specification in the common targets is {Registry:$(FrameworkRegistryBase), $(TargetFrameworkVersion), $(AssemblyFoldersSuffix), $(AssemblyFoldersExConditions)}.
- {AssemblyFolders}: Instructs the task to use the Visual Studio.NET 2003 finding-assemblies-from-registry scheme.
- {GAC}: Instructs the task to search in the Global Assembly Cache (GAC).
- {RawFileName}: Specifies the task will consider the Include value of the item to be an exact path and file name.
SerializationAssemblyFiles Optional ITaskItem[] read-only output parameter.

Contains any XML serialization assemblies found. These items are marked CopyLocal=true if and only if the reference or dependency that caused this item to exist is CopyLocal=true.

The Boolean metadata CopyLocal indicates whether the given reference should be copied to the output directory.
Silent Optional Boolean parameter.

If true, no messages are logged. The default value is false.
StateFile Optional String parameter.

Specifies a file name that indicates where to save the intermediate build state for this task.
SuggestedRedirects Optional ITaskItem[] read-only output parameter.

Contains one item for every distinct conflicting assembly identity, regardless of the value of the AutoUnify parameter. This includes every culture and PKT that was found that didn't have a suitable bindingRedirect entry in the application configuration file.

Each item optionally contains the following information:

- Include attribute: Contains the full name of the assembly family with a Version field value of 0.0.0.0
- MaxVersion item metadata: Contains the maximum version number.
SupportsBindingRedirectGeneration Optional Boolean parameter.

Set this to true on supported projects to generate binding redirects automatically (currently supported only for EXE projects).
TargetedRuntimeVersion Optional String parameter.

Specifies the runtime version to target, for example, 2.0.57027 or v2.0.57027.
TargetFrameworkDirectories Optional String[] parameter.

Specifies the path of the target framework directory. This parameter is required to determine the CopyLocal status for resulting items.

If this parameter isn't specified, no resulting items will have a CopyLocal value of true unless they explicitly have a Private metadata value of true on their source item.
TargetFrameworkMoniker Optional String parameter.

The TargetFrameworkMoniker to monitor, if any. This parameter is used for logging.
TargetFrameworkMonikerDisplayName Optional String parameter.

The display name of the TargetFrameworkMoniker to monitor, if any. This parameter is used for logging.
TargetFrameworkSubsets Optional String[] parameter.

Contains a list of target framework subset names to be searched for in the target framework directories.
TargetFrameworkVersion Optional String parameter.

The project target framework version. The default value is empty, which means there's no filtering for the references based on target framework.
TargetProcessorArchitecture Optional String parameter.

The preferred target processor architecture. Used for resolving Global Assembly Cache (GAC) references.

This parameter can have a value of x86, IA64, or AMD64.

If this parameter is absent, the task first considers assemblies that match the architecture of the currently running process. If no assembly is found, the task considers assemblies in the GAC that have ProcessorArchitecture value of MSIL or no ProcessorArchitecture value.
UnresolvedAssemblyConflicts Optional ITaskItem[] read-only output parameter.

If the parameter OutputUnresolvedAssemblyConflicts is true, then this is set to a list of information about unresolved conflicts that normally would have been outputted in MSB3277. Otherwise empty.
UnresolveFrameworkAssembliesFromHigherFrameworks Optional Boolean parameter.

If set to true, it forces framework assemblies with versions higher or equal to the version of the target framework to an unresolved state.
WarnOrErrorOnTargetArchitectureMismatch Optional String parameter.

If there's a mismatch between the target processor architecture and the architecture of a primary reference, when this is Error, an error is logged; when Warning, a warning is logged; when None, no error or warning is logged. Defaults to Warning.

Warnings

The following warnings are logged:

  • ResolveAssemblyReference.TurnOnAutoGenerateBindingRedirects

  • ResolveAssemblyReference.SuggestedRedirects

  • ResolveAssemblyReference.FoundConflicts

  • ResolveAssemblyReference.AssemblyFoldersExSearchLocations

  • ResolveAssemblyReference.UnifiedPrimaryReference

  • ResolveAssemblyReference.PrimaryReference

  • ResolveAssemblyReference.UnifiedDependency

  • ResolveAssemblyReference.UnificationByAutoUnify

  • ResolveAssemblyReference.UnificationByAppConfig

  • ResolveAssemblyReference.UnificationByFrameworkRetarget

Remarks

In addition to the parameters listed above, this task inherits parameters from the TaskExtension class, which itself inherits from the Task class. For a list of these additional parameters and their descriptions, see TaskExtension base class.

See also