SmartAssembly 8

Using the command line mode

Instead of using the SmartAssembly user interface to build your project, you can use the command line. This is useful if you want to apply a setting to multiple assemblies, or to make a change to existing settings during your build process, for example.

The console application SmartAssembly.com is stored in the same folder as SmartAssembly.exe. This is usually in %ProgramFiles%\Red Gate\SmartAssembly 8\.

To run SmartAssembly from the command line, the syntax is:

      SmartAssembly.com [switch] [projectfile | reportfile] [options]

There are two ways to use the command line:

  • Integrating SmartAssembly in your build process, or making changes to multiple SmartAssembly projects.
  • Performing regular management tasks

Integrating SmartAssembly in your build process, or making changes to multiple SmartAssembly projects.

To use the command line to integrate SmartAssembly in your build process, or to make changes to multiple SmartAssembly projects:

  1. Choose either to:
    • build an assembly based on existing SmartAssembly project settings
    • edit existing SmartAssembly project settings
    • create new SmartAssembly project settings
  2. Set the options for your SmartAssembly project
  3. Set the options for the assemblies in your project 

1. Building, creating, or editing a SmartAssembly project

/build myproject.saproj [options]

Builds the specified project. The project must have been previously created using the SmartAssembly user interface, or by using the /create switch.

The settings in the .saproj file are overridden by the specified project options, if given, but the .saproj file itself is not altered.

See the section 'Setting project options' for more information about the available project options.

/create myproject.saproj options

Creates a new .saproj file with the specified project options

The .saproj file is saved with the new options.

The assembly itself is not built.

Must be used with the /input and /output switches.

See the section 'Setting project options' for more information about the available project options.

/edit myproject.saproj options

Replaces the settings in the specified project with the specified project options. The project must have been previously created using the SmartAssembly user interface, or by using the /create switch.

The .saproj file is saved with the new options.

The assembly itself is not built.

See the section 'Setting project options' for more information about the available project options.

2. Setting project options

You can use the following switches to control how SmartAssembly processes your project.

  • If you are using the /build or /edit switch, all of these switches are optional.
    If you do not set some of the switches, the settings in your .saproj file are used instead.
  • If you are using the /create switch, you must set the /input and /output options. All other switches are optional.
    If you do not set some of the switches, the settings in bold are used instead.

Setting the input and output assemblies

/input=newassembly.exe

Overrides the input assembly specified in the *.saproj file (if applicable), using newassembly.exe instead.

Must be specified if using the /create switch.

Can be used with the /edit and /build switches to specify a new input assembly if the one in the *.saproj file has been moved to a different location.

/output=newoutput.exe

Overrides the output assembly specified in the *.saproj file (if applicable), using newoutput.exe instead.

Must be specified if using the /create switch.

Can be used with the /edit and /build switches

To overwrite the input file with the output file, use /output=$self

Signing your assembly with a strong name key

/keyfilename=[path\to\file.snk | path\to\file.pfx  | false ]

Sign the assembly with the specified strong name key file.

/keypassword=[ keypassword | false ]

Set the password for the provided PFX key.

To avoid providing password as an argument, you can use the / keypasswordenv argument to read the password from the environment variable instead.

/keypasswordenv=[ keypasswordenv | false ]

Set the environment variable name from which the PFX key password will be read.

Adding tamper protection to the assembly

/tamperprotection=[true | false ]

Apply tamper protection to the assembly.

Ignored if /keyfilename=false

Sealing classes that are not inherited

/sealclasses=[true | false ]

Seal classes that are not inherited.

Preventing Microsoft IL Disassembler from opening your assembly

/preventildasm=[true | false ]

Prevent Microsoft IL Disassembler from opening your assembly.

Setting the types / methods name mangling level

/typemethodobfuscation=[1 | 2 | 3 ]

Apply types / methods name mangling at the specified level to assemblies with nameobfuscate:true:

1 = ASCII renaming
2 = Unicode unprintable characters
3 = Unicode unprintable characters and advanced renaming

Note that this switch does not apply name mangling itself. It sets the level that will be used for assemblies with nameobfuscate:true set.

Setting the fields name mangling level

/fieldobfuscation=[1 | 2 | 3]

Apply fields name mangling at the specified level to assemblies with nameobfuscate:true:

1 = One-to-one renaming
2 = Standard renaming
3 = Advanced renaming

Note that this switch does not apply fields name mangling itself. It set the level that will be used for assemblies with nameobfuscate:true set.

Adding method parent obfuscation to the assembly

/methodparentobfuscation=[true | false ]

Apply method parent obfuscation to the assembly.

Ignored if /keyfilename=false

Adding obfuscation of compiler-generated serializable types

/cgsobfuscation=[true | false ]

Obfuscate compiler-generated serializable types. See Obfuscating serializable types generated by the compiler.

Setting strings encoding

To disable strings encoding:

/stringsencoding= false

To enable strings encoding, set /stringsencoding=true. You may specify settings for the three sub-options:

    • Use improved protection?
    • Compress and encrypt resources?
    • Cache the strings for improved performance?

/stringsencoding=true;
improved:[true | false ],
compressencrypt:[true | false ]
cache:[true | false ]

Creating a PDB file

/makepdb=[true | false | portable | windows ]

Create a PDB file.

true or windows will create a PDB file in a Windows PDB format.

portable will create a Portable PDB.

false will not create a PDB file.

Obfuscating URLs in the PDB file

/obfuscatepdburls=[true | false ]

Obfuscate URLs in the PDB file.

Ignored if /makepdb=false

Setting the application, project and company names for use in error and feature usage reports

/reportappname=""
/reportprojectname=""
/reportcompanyname=" Microsoft "

Sets the application, project and company name for use with error reporting and feature usage reporting dialogs.

Must be used with /errorreportingtemplate and/or /featureusagetemplate

Ignored if neither /errorreportingtemplate nor /featureusagetemplate are used.

Enabling error reporting

To disable error reporting:

/errorreportingtemplate= false

To enable error reporting, set errortemplate to standard or a file name. You may specify settings for the two sub-options:

    • continueonerror = Whether or not your application should try to continue after an error.
    • email = When an error report is received, an email is sent to this address. To turn of email notifications, set an empty string.

/errorreportingtemplate=[standard | path\to\template.dll];
continueonerror:[ true | false],
email:"example@example.com"

/jitoptimization=[true  | false ]

Improve error reporting performance.

If true, this option reduces the overhead, but line numbers in error reports may be inaccurate.

Enabling feature usage reporting

/featureusagetemplate=[consent1 | consent2 | auto | path\to\template.dll | false ]

Apply feature usage reporting with the specified consent dialog:

    • consent1 = Consent dialog on first run
    • consent2 = Consent dialog on second run
    • auto = Report without consent dialog
    • path\to\template.dll = Use this DLL for the consent dialog
    • false = Do not enable feature usage reporting

Copying dependencies, their configs and satellite assemblies after build

/copyDependencies=[true | false]

When true, SmartAssembly will automatically copy dependencies, their configs and satellite assemblies to the output folder after build is finished. This will allow you to run the processed assembly directly from the output folder. For more information, see Copying files and dependencies after build.

Defaults to false.

Copying additional files after build

/copyFiles=path\to\file1.txt;path\to\file2.txt;...

Copies additional files from input directory to the output directory after build. You can pass a list of multiple files, separated by a semicolon.

You can pass absolute paths or paths relative to the .saproj project file. Each file must be located within the input assembly's directory.

For more information, see Copying files and dependencies after build.

3. Setting assembly options

Some options are set per assembly.

To set these options, type the /assembly: switch, followed by the name of your assembly, then a semi-colon (;).

Add the assembly options, separated by commas, as in this example:

/assembly="MyAssembly";prune:true,merge:true,embed:true,nameobfuscate:true,dynamicproxy:true,compressencryptresources:true,controlflowobfuscate:1,compressassembly:true,encryptassembly:true,keyfilename:file.pfx,keypassword:"p@ssword"

prune:[true | false ],

Enable / Disable pruning

merge:[true | false ],

Disable / Enable dependencies merging

(Note that you cannot merge the main assembly.)

embed:[true | false ],

Disable / Enable dependencies embedding

This option is ignored if merge:true.

(Note that you cannot embed the main assembly.)

nameobfuscate:[true | false ],

Enable / Disable types and methods obfuscation and field names obfuscation

The obfuscation is applied at the levels specified for the project.

dynamicproxy:[true | false ],

Enable / Disable the references dynamic proxy

compressencryptresources:[true | false ],

Enable / Disable resources compression and encryption

controlflowobfuscate:[ False | 0 | 1 | 2 | 3 | 4],

Sets the level of control flow obfuscation to apply to the assembly:

  • False = None
  • 0 = Use attributes to set Control Flow Obfuscation, see Obfuscating the control flow
  • 1 = Basic
  • 2 = Strictly valid
  • 3 = Strongest
  • 4 = Unverifiable

compressassembly:[true | false ],
 

Enable / Disable compression when the assembly is embedded.

This option is ignored unless embed:true.

encryptassembly:[true | false ]

Whether you want to encrypt the assembly when it is embedded.

This option is ignored unless embed:true and compressassembly:true

keyfilename:[path\to\file.snk | path\to\file.pfx  | false ]

Sign the assembly with the specified strong name key file.

This option is only applicable when the assembly is merged and contains members that should remain externally accessible (see Merging assemblies others depend on).

keypassword:[ keypassword | false ]

Set the password for the provided PFX key.

To avoid providing password as an argument, you can use the keypasswordenv option instead to read the password from the environment variable (see below).

This option is only applicable when the assembly is merged and contains members that should remain externally accessible (see Merging assemblies others depend on).

keypasswordenv:[ keypasswordenv | false ]

Set the environment variable name from which the PFX key password will be read.

This option is only applicable when the assembly is merged and contains members that should remain externally accessible (see Merging assemblies others depend on).

Example usage

SmartAssembly.com /edit "C:\Documents\Visual Studio 2010\Projects\Crasher\Crasher\bin\Release\Crasher.saproj" 
     /keyfilename="./g.snk" 
     /tamperprotection=true 
     /sealclasses=true 
     /preventildasm=true 
     /featureusagetemplate=consent1 
     /fieldobfuscation=2 
     /typemethodobfuscation=3 
     /cgsobfuscation=true
     /stringsencoding=true;improved:true,compressencrypt:true,cache:true 
     /errorreportingtemplate=auto;continueonerror=true;email="example@example.com" 
     /makepdb=windows 
     /reportappname="hello world" 
     /reportprojectname="testproj" 
     /reportcompanyname="Red Gate Software" 
     /copyDependencies=true
     /copyFiles=web.config;assets\logo.png;"C:\Documents\Visual Studio 2010\Projects\Crasher\Crasher\bin\Release\README.txt"
     /assembly="Crasher";prune:true,merge:true,embed:true,nameobfuscate:true,controlflowobfuscate:3,dynamicproxy:true,compressencryptresources:true 

This example:

Takes the existing SmartAssembly project file located at C:\Documents\Visual Studio 2010\Projects\Crasher\Crasher\bin\Release\Crasher.saproj and then overwrites it, replacing the following settings. The Crasher assembly is not rebuilt.

  • Sign the assembly with the strong name key located at "./g.snk"
  • Enable tamper protection
  • Automatically seal classes wherever possible
  • Enable MSIL Disassembler protection
  • Enable Feature Usage Reporting, showing a consent dialog on the first run
  • Use Standard renaming for fields in assemblies that have fields renaming enabled
  • Use Unicode unprintable characters and advanced renaming algorithm in assemblies that have Types/Methods Name Mangling enabled
  • Enable obfuscation of compiler-generated serializable types (e.g. display classes generated by the compiler after using lambda expressions)
  • Enable Strings Encoding with Improved Protection, Compress and Encrypt the Strings and enable the cache
  • Enable Automatic Error Reporting without a dialog box, trying to continue when an error occurs
  • Generate Windows PDB files for the assembly
  • For the purposes of Automated Error Reporting and Feature Usage Reporting, name the application 'Hello World', name the project 'testproj', set the company name to 'Red Gate Software' and set the email address to 'example@example.com'. (This is the email address that will be sent a message whenever a new error report arrives.)
  • Enable copying all dependencies, their configs and satellite assemblies to the output directory.
  • Enable copying files located next to the input assembly ("web.config", "assets\logo.png", and "README.txt") to the output directory.

Then, within the assembly called "Crasher":

  • Enable Pruning
  • Enable Merging
  • Embed the assembly into the main assembly (which will have been set in the Crasher.saproj file already)
  • Enable Types/Methods Name Mangling and Fields Name Mangling
  • Enable Control Flow Obfuscation at the 'Strongest' level
  • Enable the Dynamic References Proxy
  • Enable Resources Compression and Encryption

Changing database settings (permanently or per-session)

Available database options

SQLite database
/dbType=SQLiteRequired. Must be set to SQLite when using SQLite database.
/dbPath=C:\path\to\sqlite-database-file.dbRequired. Absolute path to the file where SQLite database is saved.
SQL Server database
/dbType=SQLServerRequired. Must be set to SQLServer when using SQL Server database.
/dbServer="database instance"

Required. Your database host\instance. For example:

/dbServer="localhost\SQL2016"
/dbConn="connection string"

Required. Connection string used to connect to the database. For example:

/dbServer="Server=localhost\SQL2016;Database=SmartAssembly;User Id=regularUser;Password=userPassword;"

This connection string will also be used to create a SmartAssembly database when /dbCreatorConn is omitted.

/dbCreatorConn="connection string"

Optional. Connection string used to create a SmartAssembly database. For example:

/dbServer="Server=localhost\SQL2016;Database=SmartAssembly;User Id=admin;Password=adminPassword;"

Changing current database permanently

To permanently change the database settings, use the /settings switch. This will have the same effect as changing the settings in the GUI or editing %PROGRAMDATA%\Red Gate\SmartAssembly 8\SmartAssembly.settings file.

SmartAssembly.com /settings /dbType=SQLite /dbPath=C:\path\to\sqlite-database-file.db

Changing current database temporarily (per-session)

You can connect to a different database only in a selected session. This can be useful if you don't want to preserve information about test builds (by saving them to easily-discardable database file), or if you want to import an error report to a different database then the one you're currently connected to.

In this case you can just pass the database options to any SmartAssembly switch.

SmartAssembly.com /build ConsoleApp.saproj /dbType=SQLite /dbPath=C:\path\to\sqlite-database-file.db
SmartAssembly.com /addReport MyReportFile.saencryptedreport /dbType=SQLServer /dbServer="localhost\SQL2016" /dbConn="Server=localhost\SQL2016;Database=SmartAssembly;User Id=regularUser;Password=userPassword;"

Logging

You can control logging when using the command line. This might be especially useful when investigating an issue in remote environments (such as Azure).

/log

Outputs log information directly to console.

Log level is the same as the one set in the GUI but can be overridden using /logLevel option.

/logLevel=[ None | Verbose | Warning | Error ]

Sets the verbosity of the log for the current session. The higher the level, the more information will be logged.

  • Verbose: Logs all available information.
  • Warning: Only logs warnings and errors.
  • Error: Only logs errors.
  • None: Disables logging.

Setting the log level has an effect both on logs saved to file and those displayed in the command line.

Note: Enabling verbose logging may significantly affect performance.

/logFile=C:\path\to\custom.log

Specifies the file where the log will be saved.

If not specified, the log will be saved to the default file, located in %LOCALAPPDATA%\Red Gate\Logs\SmartAssembly\ folder.

If used with /log option, the log will be saved to file and displayed in the command line at the same time.

Performing regular management tasks

You can also use the following command line switches to perform management tasks related to your SmartAssembly installation.

These switches are used on their own; they are not used with the /create, /build, or /edit switches.

/compactdb

Compacts the SmartAssembly database (smartassembly\database.mdb).

Does not apply to SmartAssembly installations using SQL server.

/downloadnewreports

Download new feature usage and error reports.

/addreport myencryptedreport.
saencryptedreport

(With Professional Edition only)

When you get an encrypted report file sent to you via email, you can either double-click the file (if it has the correct .saencryptedreport extension) or run this command line option. In both cases, the report is added to the database, as if it had been downloaded from the web-service.

/deactivateSerialDeactivates SmartAssembly. See Deactivating for more information.

Didn't find what you were looking for?