AL (Assembly Linker) task

The AL task wraps AL.exe, a tool that is distributed with the Windows Software Development Kit (SDK). This Assembly Linker tool is used to create an assembly with a manifest from one or more files that are either modules or resource files. Compilers and development environments might already provide these capabilities, so it is often not necessary to use this task directly. The Assembly Linker is most useful to developers needing to create a single assembly from multiple component files, such as those that might be produced from mixed-language development. This task does not combine the modules into a single assembly file; the individual modules must still be distributed and available in order for the resulting assembly to load correctly. For more information on AL.exe, see Al.exe (Assembly Linker).

Parameters

The following table describes the parameters of the AL task.

Parameter	Description
AlgorithmID	Optional String parameter. Specifies an algorithm to hash all files in a multifile assembly except the file that contains the assembly manifest. For more information, see the documentation for the /algid option in Al.exe (Assembly Linker).
BaseAddress	Optional String parameter. Specifies the address at which a DLL will be loaded on the user's computer at run time. Applications load faster if you specify the base address of the DLLs, rather than letting the operating system relocate the DLLs in the process space. This parameter corresponds to the /baseaddress.
CompanyName	Optional String parameter. Specifies a string for the Company field in the assembly. For more information, see the documentation for the /comp[any] option in Al.exe (Assembly Linker).
Configuration	Optional String parameter. Specifies a string for the Configuration field in the assembly. For more information, see the documentation for the /config[uration] option in Al.exe (Assembly Linker).
Copyright	Optional String parameter. Specifies a string for the Copyright field in the assembly. For more information, see the documentation for the /copy[right] option in Al.exe (Assembly Linker).
Culture	Optional String parameter. Specifies the culture string to associate with the assembly. For more information, see the documentation for the /c[ulture] option in Al.exe (Assembly Linker).
DelaySign	Optional Boolean parameter. true to place only the public key in the assembly; false to fully sign the assembly. For more information, see the documentation for the /delay[sign] option in Al.exe (Assembly Linker).
Description	Optional String parameter. Specifies a string for the Description field in the assembly. For more information, see the documentation for the /descr[iption] option in Al.exe (Assembly Linker).
EmbedResources	Optional ITaskItem[] parameter. Embeds the specified resources in the image that contains the assembly manifest. This task copies the contents of the resource file into the image. The items passed in to this parameter may have optional metadata attached to them called LogicalName and Access. The LogicalName metadata is used to specify the internal identifier for the resource. The Access metadata can be set to private in order to make the resource not visible to other assemblies. For more information, see the documentation for the /embed[resource] option in Al.exe (Assembly Linker).
EvidenceFile	Optional String parameter. Embeds the specified file in the assembly with the resource name of Security.Evidence. You cannot use Security.Evidence for regular resources. This parameter corresponds to the /e[vidence] option in Al.exe (Assembly Linker).
ExitCode	Optional Int32 output read-only parameter. Specifies the exit code provided by the executed command.
FileVersion	Optional String parameter. Specifies a string for the File Version field in the assembly. For more information, see the documentation for the /fileversion option in Al.exe (Assembly Linker).
Flags	Optional String parameter. Specifies a value for the Flags field in the assembly. For more information, see the documentation for the /flags option in Al.exe (Assembly Linker).
GenerateFullPaths	Optional Boolean parameter. Causes the task to use the absolute path for any files that are reported in an error message. This parameter corresponds to the /fullpaths option in Al.exe (Assembly Linker).
KeyContainer	Optional String parameter. Specifies a container that holds a key pair. This will sign the assembly (give it a strong name) by inserting a public key into the assembly manifest. The task will then sign the final assembly with the private key. For more information, see the documentation for the /keyn[ame] option in Al.exe (Assembly Linker).
KeyFile	Optional String parameter. Specifies a file that contains a key pair or just a public key to sign an assembly. The compiler inserts the public key in the assembly manifest and then signs the final assembly with the private key. For more information, see the documentation for the /keyf[ile] option in Al.exe (Assembly Linker).
LinkResources	Optional ITaskItem[] parameter. Links the specified resource files to an assembly. The resource becomes part of the assembly, but the file is not copied. The items passed in to this parameter may have optional metadata attached to them called LogicalName, Target, and Access. The LogicalName metadata is used to specify the internal identifier for the resource. The Target metadata can specify the path and filename to which the task copies the file, after which it compiles this new file into the assembly. The Access metadata can be set to private in order to make the resource not visible to other assemblies. For more information, see the documentation for the /link[resource] option in Al.exe (Assembly Linker).
MainEntryPoint	Optional String parameter. Specifies the fully qualified name (class.method) of the method to use as an entry point when converting a module to an executable file. This parameter corresponds to the /main option in Al.exe (Assembly Linker).
OutputAssembly	Required ITaskItem output parameter. Specifies the name of the file generated by this task. This parameter corresponds to the /out option in Al.exe (Assembly Linker).
Platform	Optional String parameter. Limits which platform this code can run on; must be one of x86, Itanium, x64, or anycpu. The default is anycpu. This parameter corresponds to the /platform option in Al.exe (Assembly Linker).
ProductName	Optional String parameter. Specifies a string for the Product field in the assembly. For more information, see the documentation for the /prod[uct] option in Al.exe (Assembly Linker).
ProductVersion	Optional String parameter. Specifies a string for the ProductVersion field in the assembly. For more information, see the documentation for the /productv[ersion] option in Al.exe (Assembly Linker).
ResponseFiles	Optional String[] parameter. Specifies the response files that contain additional options to pass through to the Assembly Linker.
SdkToolsPath	Optional String parameter. Specifies the path to the SDK tools, such as resgen.exe.
SourceModules	Optional ITaskItem[] parameter. One or more modules to be compiled into an assembly. The modules will be listed in the manifest of the resulting assembly, and will still need to distributed and available in order for the assembly to load. The items passed into this parameter may have additional metadata called Target, which specifies the path and filename to which the task copies the file, after which it compiles this new file into the assembly. For more information, see the documentation for Al.exe (Assembly Linker). This parameter corresponds to the list of modules passed into Al.exe without a specific switch.
TargetType	Optional String parameter. Specifies the file format of the output file: library (code library), exe (console application), or win (Windows-based application). The default is library. This parameter corresponds to the /t[arget] option in Al.exe (Assembly Linker).
TemplateFile	Optional String parameter. Specifies the assembly from which to inherit all assembly metadata, except the culture field. The specified assembly must have a strong name. An assembly that you create with the TemplateFile parameter will be a satellite assembly. This parameter corresponds to the /template option in Al.exe (Assembly Linker).
Timeout	Optional Int32 parameter. Specifies the amount of time, in milliseconds, after which the task executable is terminated. The default value is Int.MaxValue, indicating that there is no time out period.
Title	Optional String parameter. Specifies a string for the Title field in the assembly. For more information, see the documentation for the /title option in Al.exe (Assembly Linker).
ToolPath	Optional String parameter. Specifies the location from where the task will load the underlying executable file (Al.exe). If this parameter is not specified, the task uses the SDK installation path corresponding to the version of the framework that is running MSBuild.
Trademark	Optional String parameter. Specifies a string for the Trademark field in the assembly. For more information, see the documentation for the /trade[mark] option in Al.exe (Assembly Linker).
Version	Optional String parameter. Specifies the version information for this assembly. The format of the string is major.minor.build.revision. The default value is 0. For more information, see the documentation for the /v[ersion] option in Al.exe (Assembly Linker).
Win32Icon	Optional String parameter. Inserts an .ico file in the assembly. The .ico file gives the output file the desired appearance in File Explorer. This parameter corresponds to the /win32icon option in Al.exe (Assembly Linker).
Win32Resource	Optional String parameter. Inserts a Win32 resource (.res file) in the output file. For more information, see the documentation for the /win32res option in Al.exe (Assembly Linker).

ToolTaskExtension parameters

This task inherits from the ToolTaskExtension class, which inherits from the ToolTask class, which itself inherits from the Task class. This inheritance chain adds several parameters to the tasks that derive from them.

The following table describes the parameters of the base classes:

Parameter	Description
EchoOff	Optional bool parameter. When set to true, this task passes /Q to the cmd.exe command line such that the command line does not get copied to stdout.
EnvironmentVariables	Optional String array parameter. Array of environment variable definitions, separated by semicolons. Each definition should specify an environment variable name and value separated by an equal sign. These variables are passed to the spawned executable in addition to, or selectively overriding, the regular environment block. For example, Variable1=Value1;Variable2=Value2.
ExitCode	Optional Int32 output read-only parameter. Specifies the exit code that is provided by the executed command. If the task logged any errors, but the process had an exit code of 0 (success), this is set to -1.
LogStandardErrorAsError	Optional bool parameter. If true, all messages received on the standard error stream are logged as errors.
StandardErrorImportance	Optional String parameter. Importance with which to log text from the standard out stream.
StandardOutputImportance	Optional String parameter. Importance with which to log text from the standard out stream.
Timeout	Optional Int32 parameter. Specifies the amount of time, in milliseconds, after which the task executable is terminated. The default value is Int.MaxValue, indicating that there is no time out period. Time-out is in milliseconds.
ToolExe	Optional string parameter. Projects may implement this to override a ToolName. Tasks may override this to preserve the ToolName.
ToolPath	Optional string parameter. Specifies the location from where the task loads the underlying executable file. If this parameter is not specified, the task uses the SDK installation path that corresponds to the version of the framework that is running MSBuild.
UseCommandProcessor	Optional bool parameter. When set to true, this task creates a batch file for the command line and executes it by using the command-processor instead of executing the command directly.
YieldDuringToolExecution	Optional bool parameter. When set to true, this task yields the node when its task is executing.

Example

The following example creates an assembly with the specified options.

<AL
    EmbedResources="@(EmbeddedResource)"
    Culture="%(EmbeddedResource.Culture)"
    TemplateFile="@(IntermediateAssembly)"
    KeyContainer="$(KeyContainerName)"
    KeyFile="$(KeyOriginatorFile)"
    DelaySign="$(DelaySign)"

    OutputAssembly=
       "%(EmbeddedResource.Culture)\$(TargetName).resources.dll">

    <Output TaskParameter="OutputAssembly"
        ItemName="SatelliteAssemblies"/>
</AL>

See also

• Task reference
• Tasks