Page tree
Skip to end of metadata
Go to start of metadata

The Native Image Generator (NGen 2.0) Install Action enables the creation and installation of a native image for an assembly and its dependencies. Assemblies with native images run faster on the current machine because they can bypass the .NET Just-In-Time compiler.


Assembly

Specify assembly by file

Enter the explicit path of an assembly to precompile.

Specify an assembly in the global assembly cache

Specify the full display name of an assembly in the global assembly cache. Separate extra properties with commas.

e.g. "bobsAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=1138abc1dabcdfle2".

Framework Version

Use default framework version (vX.X) / Use vX.X

Allows the selection of the .NET version to use for the tool. The minimum is .NET v2.0.

Use 64-bit tools

This options specifies as whether to force the usage of 64-bit tools on a 64-bit system or not.  As FinalBuilder is currently a 32-bit application it will default to running the 32-bit version on a 64-bit system.  Check this option if you require the 64-bit version to be run.

On this page:

 



Options

Scenarios

Generate images for use with a debugger

If this option is turned on debug information is included in the generated image. 

Generate images for use with profiler

If this options is turned on a profiler will be able to load the generated image. 

Minimise the native image dependencies that are generated

If this option is turned on the native image will be generated with a minimum of dependencies.  This is not recommended because non-native dependencies will cause the Just In Time compiler to be invoked, negating the benefits of Native Images.

Configuration

Configure using executable assembly

The assembly configuration can be taken from an executable configuration.  This allows NGen to get a better idea as to what dependencies would be loaded by the assembly.

Configure using appbase directory

The directory to use as the application base when locating dependencies for the supplied assembly.

Options

Queue for execution by the native image service

Rather than installing directly, the generation and installation can be queued for execution by the Native Image Service. There are three levels of priority lowest, normal, and highest.

Verbose execution

Includes the maximum amount of information while generating the native assembly. Useful for debugging issues with the action, does slow down generation however. Therefore we recommend turning this off during normal script runs.


Action Scripting

Toggle All | Expand All | Collapse All

Action Specific Scripting

Other

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
AppBasePath
Action.AppBasePath = 'C:\Projects\SimpleProject\';
any text[blank]On save

Sets the Configure using appbase directory value.

AssemblyName
Action.AssemblyName = 'bobsAssembly, Version=1.0.0.0, Culture=neutral, ' +
    'PublicKeyToken=1138abc1dabcdfle2';
any text[blank]On save

Sets the Specify an assembly in the global assembly cache value.

AssemblyPath
Action.AssemblyPath = 'C:\Projects\SimpleProject\Output\SimpleProject.dll'
any text[blank]On saveSets the Specify assembly by file value.
Debug
Action.Debug = true;
true, falsefalseOn saveSets the Generate images for use with a debugger value. 
ExeConfigPath
Action.ExeConfigPath = 'C:\Projects\SimpleProject\Output\Config.exe';
any text[blank]On saveSets the Configure using executable assembly value. 
NoDep
Action.NoDep = true;
true, falsefalseOn saveSets the Minimise the native image dependencies that are generated value. 
Profile
Action.Profile = true;
true, falsefalseOn saveSets the Generate images for use with profiler value. 
Queued
Action.Queued = true;
true, falsefalseOn saveSets the Queue for execution by the native image service value. 
QueuePriority
Action.QueuePriority = 2;
1, 2, or 33On saveSets the priority level for the Queue property. 
UseAppBase
Action.UseAppBase = true;
true, falsefalseOn saveWhen set to true it enables the usage of the AppBasePath property.
UseAssemblyName
Action.UseAssemblyName = true;
true, falsefalseOn saveWhen set to true it enables the usage of the AssemblyPath property.
UseExecConfig
Action.UseExecConfig = true;
true, falsefalseOn saveWhen set to true it enables the usage of the ExeConfigPath property. 
Verbose
Action.Verbose = true;
true, falsefalseOn saveSets the Verbose execution value. 

Common Scripting Properties

Behaviour

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
Enabled
Action.Enabled = false;
true, falsetrueOn save

Whether the action is enabled or disabled. Disabled actions are not considered part of a script. When the script is run they are ignore completely.

Has to be set prior to the action being selected to run. This means the latest this can be set is in the actions parent.

IgnoreFailure
Action.IgnoreFailure = true;
true, falsefalseOn save

When set to true, the action will always report as having successfully completed. The actions run result is ignored. Even if the action run result is failure, the build will continue.

Has to be set before the action is run to have any affect.

PauseInterval
Action.PauseInterval = 2;
0 to 18000000 (5 hours)0On save

The number of milliseconds to pause after the completion of an action. The IDE allows users to skip pause intervals if required. The command line runner does not allow for the skipping of this interval.

Setting this is preferable to sleeping in a script as the action continues to be responsive, and handles termination requests.

Has to be set prior to the action run to have any affect.

MaxRetryAttempts
Action.MaxRetryAttempts = 3;
any positive 32-bit integer 0On save

The number of times to retry an action when it fails. Each failed run of the action is counted as a retry attempt. Once all the retry attempts are exhausted the action will return the result of the last retry attempt.

On a successful run this counter is reset for the next time the action is called. This is important for loops which contain actions with retry attempts set.

Has to be set prior to the run of the action to have any affect.

RetryPauseInterval
Action.RetryPauseInterval = 500;
any positive 32-bit integer 1000On save

The number of milliseconds to wait before running a retry of an action. This starts counting directly after the action fails and is not able to be skipped. Useful for waiting resources to become available, or locks to be released.

Has to be set before to the run of the action to have any affect.

Description

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
Comment
Action.Comment = 'Loads config for build';
any text (single line shown)[blank]On saveAllows you to add documentation to the action instance.
Description
Action.Description = 'Upload [ Installer ]';
any text (single line shown)[action dependent]On saveThe text shown in the IDE for the action. Describes the purpose of the action. Clear this property to revert to an automatically generated description.

Identity

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
ActionName
Action.SendLogMessage(Action.ActionName, stInformation);
any text (read only)[action dependant]NoThe name of the action which is shown in the action types list. This is defined by the action and is not able to be changed. All actions of the same type will have the same name.
Package
Action.SendLogMessage(Action.Package, stInformation);
any text (read only)[action dependant]NoThe filename of the package from which the action was loaded. All actions from the same package will have the same package filename.

Logging

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
ActionLogTitle
Action.ActionLogTitle = 'Upload [ Installer ]';
any text (single line shown)Action.DescriptionOn saveSets a different description for the action for logging purposes. This description is only ever used in the log.
ExpandActionLogTitle
Action.ExpandActionLogTitle = false;
true, falsetrueOn saveEnables variables in the ActionLogTitle to be expanded. The expansion occurs at the time of logging.
HideActionFromLog
Action.HideActionFromLog = true;
true, falsefalseOn saveHides the action from the log. If the action execution results in an error the action is logged, effectively ignoring this setting.
LogActionProperties
Action.LogActionProperties = true;
true, falsefalseOn saveRecords the properties of the action to the log before the action is run.
LogToVariable
Action.LogToVariable = 'MyVariable';
text name of variable[blank]On saveSpecifies which variable should have the output of the action written to it. The selected variable is required to be available to the action, otherwise an error will be raised. The variable will contain the actions output after the action has run.
SuppressStatusMessages
Action.SuppressStatusMessages = true;
true, falsefalseOn saveStops the logging of all the actions status messages. This stops the action status messages from being generated, so OnStatusMessage events will not fire when this options is turned on.

Other

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
ErrorCount
if (Action.ErrorCount > 0)
   Action.SendLogMessage('There were errors', stError);
any positive 32-bit integer (read only)0NoReturns the number of errors the action has encountered during its run. Some actions can encounter more than one error before failing.
Errors
Action.SendLogMessage('Errors encountered' + Action.Errors, stError);
any text (read only)[blank]NoReturns the description of all the errors encounter by the action during it run. The error descriptions are concatenated with new lines between each entry.
Locked
Action.Locked = true;
true, falsefalseOn saveLocks the properties on the action so that they can not be changed through the action dialog. When turned on, the only property which can be altered is the locked property itself. Turning this off again means all other properties can be altered through the actions edit dialog.
TimedOut
if (Action.TimedOut)
   Action.SendLogMessage('Action timed out', stWarning);
true, false (read only)falseNoSet to true when the action has timed out waiting for the underlying tool to complete.

Execute Action Scripting Properties

Extra Command Line

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
ExtraCmdLineParamsAtEnd
Action.ExtraCmdLineParamsAtEnd = '\s \p Text.txt';
any text (validated by underlying tool)[blank]On saveSpecifies additional command line parameters for the underlying tool. These are added after all command line parameters added by the action.
ExtraCmdLineParamsAtStart
Action.ExtraCmdLineParamsAtStart = '\q \ignore:3';
any text (validated by underlying tool)[blank]On saveSpecifies additional command line parameters for the underlying tool. These are added before all command line parameters added by the action.

Process

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
UseErrorDialogMonitor
Action.UseErrorDialogMonitor = true;
true, falsefalseOn saveSpecifies whether to automatically watch for an error dialog which has stalled the underlying tool. The dialog will be closed, and if this is not possible the process will be terminated. This option does not work with all underlying tools.
ProcessPriority
Action.ProcessPriority = tpBelowNormal;
tpIdle, tpBelowNormal, tpNormal, tpAboveNormaltpNormalOn saveSpecifies at what priority processes spawned by the action will have. Note that setting an idle priority will most likely mean the action will not progress. tpIdle is only included for completeness, typically it should not be used.
ProcessorAffinity
Action.ProcessorAffinity = 243;
0 (unset), 1 to 255 (bit mask)0On save

Specifies which processors spawned processes of the action will be allowed to run on. The value is in the form of a bit mask. The mask depends on the number of processors available on the running machine.

A bit mask of 1101 1111 ( = 223 ) for a six processor machine would mean spawned processes could run all but the 6th processor.

Run As User

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
ImpersonateUserName
Action.ImpersonateUserName = 'domain/username';
[domain]/[username][blank]On save

Specifies the user credentials with which to run processes spawned by the action. The user that FinalBuilder is running under, will require the permissions to elevate their rights and impersonate other users for this to be allowed.

ImpersonateUser needs to be set to true for this to be used.

ImpersonateUseNetCredOnly
ActionImpersonateUseNetCredOnly = true;
true, falsefalseOn save

Specifies whether the impersonation should only use the network component of the supplied users credentials. This allows for simpler access to network resources which have restricted access.

ImpersonateUser needs to be set to true for this to be used.

ImpersonateUser
Action.ImpersonateUser = true;
true, falsefalseOn saveSpecifies whether processes spawned by the action should be run under a different set of user credentials.
ExpandImpersonateToken
Action.ExpandImpersonateToken = true;
true, falsefalseOn saveSpecifies whether to expand variables found within the impersonate user password. This is handy for setting the password to a variable and then loading from a secure file, or using a passed in variable when the script is run.
ImpersonateUserPassword
Action.ImpersonateUserPassword = '8as0dk9JLa!df';
any text[blank]On saveSpecifies the password to use for the user who is being impersonated. Once set the value is encrypted for saving into the project (if its saved after this script is called).

Timeout

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
EnableTimeout
Action.EnableTimeout = true;
true, falsefalseOn saveSpecifies whether the action should fail if the TimeoutLength expires. The TimeoutLength is counted from the start of the action running.
TimeoutLength
Action.TimeoutLength = 2;
any positive 32-bit integer
1On saveSpecifies the number of minutes to wait after the start of an action to complete. If the action does not complete before the timeout length has expired the action is given a failure result, and the TimedOut property is set to true.

.NET Scripting Properties

Other

 Click here to expand...
Script PropertyExample (Javascript)Valid ValuesDefaultPersistedDescription
OverrideSDKDefault
Action.OverrideSDKDefault = true;
true, falsefalseOn save

Specifies whether the default SDK version set in the FinalBuilder options should be overridden for this action. Setting this to true will mean the SDK version will be taken from the SDKVersion property on the action.

Architecture
Action.Architecture = ta32;
ta32, ta64ta32On save

Whether to use the 32-bit or 64-bit versions of the underlying tool. Note that some tools can not be run as the 64-bit version from a 32-bit process. As a result these tools will either report an error or simply link to the 32-bit version. Check each tools MSDN reference for more details.

SDKVersion
Action.SDKVersion = "v4.0";

v2.0, v3.0, v3.5, v4.0, or

any other installed .NET version

set in optionsOn save

Sets the overridden SDK version for the underlying tool. The specified SDK version needs to be installed on the machine otherwise an error will be raised saying the specific tool could not be found.


Scripting Events

 Click here to expand...

Script Event

Parameters

Description

BeforeAction

Action : <TAction>

The instance of the current action. Allows access to the action properties and methods.

All properties are set to the values provided by the action editor or their defaults.

SkipAction : Boolean
An out parameter which allows for the action to be skipped during a build. Default is false.

Called before the action is executed. When called all properties on the action have been initialised to those provided in the action editor dialog. Properties which have not been provided are set to their defaults.

Use this event to change anything about the action or perform operations which need to occur before the action is run. Also this event can be used to skip an action entirely. If the action is skipped it will report as such in the log, and no more processing of the action or its scripts will occur.

Run-time errors in this script will stop the action from running and the action will report as failed.

AfterAction

Action : <TAction>

The instance of the current action. Allows access to the action properties and methods.

All properties are set to the values used during the run of the action.

ActionResult : boolean
Indicates if the action succeeded or failed. Allows for the handling or overriding of the actions status during a build.
Continue : boolean

Indicates if the build should continue after this action has completed or not.

Return false to stop the build, return true to ignore the build result and continue the build. Default is unset.

Called after the action has executed. All properties on the action will be the same as when the action was run. Any properties which change during the run will be available at this point (e.g. Exit codes properties).

This event allows for the handling of action error states that where are not directly handled by the action itself. For example if an certain error code is acceptable it can be logged and ignored through this event.

Conversely a certain successful run condition that is not desirable could be reported through this event. To achieve these outcomes set the ActionResult and Continue parameters to values which reflect the true outcome of the actions run.

Run-time errors produced by this script will cause the action to report as failed. Setting of either the ActionResult or Continue parameters will not override this.

OnStatusMessage

Action : <TAction>

The instance of the current action. Allows access to the action properties and methods.

All properties are set to values used during the run of the action.

StatusMessage : TStatusMessage
The status message object contains all information relating to the message being logged (Lines, MessageText, MessageTitle, and Progress).

Called whenever the action generates a log message.

Actions will generate this event when the action has received output from the underlying tool, or when the action itself has something to report. The StatusMessage may contain zero-to-many lines of text and is in the format directly seen in the log.

As formatting depends on the tool being used we advise using the RegExp function to parse the output if required. Also please review the TString object type for more information on how to access the contents of the messages.

Run-time errors produced by this script will cause the action to report as failed.


  • No labels