Share via


ResolveAssemblyReference Task

Determines all assemblies that depend on the specified assemblies. This includes second and nth-order dependencies.

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 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 will work. If SpecificVersion is not 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.

  • 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 will be resolved into full assembly paths. Items with non-empty 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 does not have to be opened to get the name.

AutoUnify

Optional Boolean parameter.

If 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 so that the highest version assembly is chosen. A result of this is that there will never be a warning about conflicting assemblies because every conflict will have been resolved. Each distinct remapping will cause a high priority comment that indicates the old and new versions and the fact that this was done automatically because AutoUnify was true.

If false, no assembly version remapping will occur automatically. When two versions of an assembly are present, there will be a warning. Each distinct conflict between different versions of the same assembly will cause a high priority comment. After all these comments are displayed, there will be a single warning with a unique error code and 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 will be considered when the SearchPaths parameter contains {CandidateAssemblyFiles} as one of the paths to consider.

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.

FilesWritten

Optional ITaskItem[] output parameter.

Contains the items written to disk.

FindDependencies

Optional Boolean parameter.

If true, dependencies will be found. Otherwise, only primary references are found. The default value is true.

FindRelatedFiles

Optional Boolean parameter.

If true, related files such as .pdb files and .xml files will be found. The default value is true.

FindSatellites

Optional Boolean parameter.

If true, satellite assemblies will be found. The default value is true.

FindSerializationAssemblies

Optional Boolean parameter.

If true, then the task searches for serialization assemblies. The default value is true.

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.

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 is only one TargetFrameworkDirectories element, then any items in this list that lack the "FrameworkDirectory" metadata are treated as though they are 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 is only one TargetFrameworkDirectories element, then any items in this list that lack the "FrameworkDirectory" metadata are treated as if they are set to the unique value that is passed

to TargetFrameworkDirectories.

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 does not 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.

SatelliteFiles

Optional ITaskItem[] read-only output parameter.

Specifies any satellite files found. These will be 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 the following types of values:

  • A directory path.

  • {HintPathFromItem}: Specifies that the task will examine the HintPath metadata of the base item.

  • {CandidateAssemblyFiles}: Specifies that the task will examine the files passed in through the CandidateAssemblyFiles parameter.

  • {Registry:_AssemblyFoldersBase_, _RuntimeVersion_, _AssemblyFoldersSuffix_}:

  • {AssemblyFolders}: Specifies the task will use the Visual Studio.NET 2003 finding-assemblies-from-registry scheme.

  • {GAC}: Specifies the task will search in the GAC.

  • {RawFileName}: Specifies the task will consider the Include value of the item to be an exact path and file name.

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 did not 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.

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 is not specified, no resulting items will be have a CopyLocal value of true unless they explicitly have a Private metadata value of true on their source item.

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 is 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.

See Also

Concepts

MSBuild Tasks

Other Resources

MSBuild Task Reference

Change History

Date

History

Reason

July 2008

Added these parameters:

  • AllowedAssemblyExtensions

  • AllowedRelatedFileExtensions

  • FindSerializationAssemblies

  • FullTargetFrameworkSubsetNames

  • IgnoreDefaultInstalledAssemblyTables

  • IgnoreDefaultInstalledAssemblySubsetTables

  • InstalledAssemblySubsetTables

  • InstalledAssemblyTables

  • TargetFrameworkSubsets

  • TargetFrameworkVersion

SP1 feature change.