AL (Assembly Linker) Task

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

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

The following table describes the parameters of the AL task.

ParameterDescription
AlgorithmIDOptional 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).
BaseAddressOptional 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 /base[address] option in Al.exe (Assembly Linker).
CompanyNameOptional 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).
ConfigurationOptional 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).
CopyrightOptional 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).
CultureOptional 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).
DelaySignOptional 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).
DescriptionOptional 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).
EmbedResourcesOptional 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).
EvidenceFileOptional 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).
ExitCodeOptional Int32 output read-only parameter.

Specifies the exit code provided by the executed command.
FileVersionOptional 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).
FlagsOptional 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).
GenerateFullPathsOptional 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).
KeyContainerOptional 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).
KeyFileOptional 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).
LinkResourcesOptional 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).
MainEntryPointOptional 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).
OutputAssemblyRequired 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).
PlatformOptional 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).
ProductNameOptional 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).
ProductVersionOptional 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).
ResponseFilesOptional String[] parameter.

Specifies the response files that contain additional options to pass through to the Assembly Linker.
SdkToolsPathOptional String parameter.

Specifies the path to the SDK tools, such as resgen.exe.
SourceModulesOptional 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.
TargetTypeOptional 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).
TemplateFileOptional 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).
TimeoutOptional 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.
TitleOptional 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).
ToolPathOptional 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.
TrademarkOptional 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).
VersionOptional 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).
Win32IconOptional 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).
Win32ResourceOptional 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).

In addition to the parameters listed above, this task inherits parameters from the ToolTaskExtension class, which itself inherits from the ToolTask class. For a list of these additional parameters and their descriptions, see ToolTaskExtension Base Class.

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>  

Task Reference
Tasks

Show: