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>