Configuration Files

JSILc allows you to control translation of your applications and libraries by providing one or more JSIL Configuration Files with the extension .jsilconfig.

Where JSILc finds configuration files

• JSILc will automatically load any .jsilconfig files you pass it on the command line and apply them to all files translated during that session.
• JSILc will search next to each .sln file translated for a matching .jsilconfig file: Foo.sln.jsilconfig. This configuration file will affect only that solution and its outputs.
• JSILc will search next to each .exe or .dll file translated for a matching .jsilconfig file: Foo.dll.jsilconfig. This configuration file will affect that assembly and its dependencies. Note that this only works for assemblies being translated directly; you cannot set per-assembly configuration for dependencies.
• A file named defaults.jsilconfig is automatically placed in the JSILc bin folder during the compile process. This file will be automatically loaded and applied during translation unless disabled (see ApplyDefaults below).

Configuration file format

A configuration file is a single JSON dictionary. The dictionary can contain the following setting keys:

Key	Type	Default Value
AnalyzerSettings	Dictionary
See the 'Analyzer Settings' section below.
ApplyDefaults	Boolean	true
If true, the default project settings will be applied from defaults.jsilconfig. Note that default project settings never override settings you have specified yourself.
Assemblies	Dictionary
See the 'Assembly Settings' section below.
AutoLoadConfigFiles	Boolean	true
If true, JSILc will automatically search for and load .jsilconfig files next to solutions and assemblies, as described above.
BuildSourceMap	Boolean	false
If true, JSILc will generate source map (*.js.map) if symbol information presents.
CodeGenerator	Dictionary
See the 'Code Generator Settings' section below.
IncludeDependencies	Boolean	false
Wraps resulted assembly file with IIFE and includes inside all used assembly references. Resulted assembly file is independent from manifest and should not affect another assembly files, so it could be reused.
FrameworkVersion	Float	automatic
Allows you to specify which version of the .NET framework your application uses. Currently, JSILc only supports 3.5 and 4.0.
GenerateContentManifest	Boolean	true
If true, the .manifest.js file produced by JSIL will include a content manifest listing the paths and sizes of all the scripts and other content referenced by your project. For XNA games, this will include all your XNA assets. This manifest can be used in order to automatically load all the necessary files for your application (JSIL.Browser.js uses it automatically if present).
GenerateSkeletonsForStubbedAssemblies	Boolean	false
If true, any stubbed assemblies translated will be produced as a 'skeleton', where the class definitions are replaced with JSIL.ImplementExternals calls and each method body is replaced with a throw statement. These skeletons can easily be copy-pasted to create your own JavaScript implementation of .NET libraries.
IncludeDependencies	Boolean	true
If true, any assembly loaded for translation will be automatically scanned for dependent assemblies, and those dependent assemblies will be loaded and translated with it. This is necessary in order to produce working JavaScript, but you can disable it if you are certain that none of the dependent assemblies' types or functions are used.
OutputDirectory	String	none
Specifies the location where all output JavaScript, Manifests and log files will be placed. Supports Variable Expansion.
Profile	String	automatic
Specifies the name of a specific Profile to use during translation.
ProfileSettings	Dictionary
Specifies settings for the profile being used during translation. The default profile has no settings.
SolutionBuilder	Dictionary
See the 'Solution Builder Settings' section below.
UseDefaultProxies	Boolean	true
If true, JSILc will automatically load the default proxies library for the FrameworkVersion you've specified. If false, no default proxies library will be loaded and you must specify one yourself. This is useful if you are using a custom version of mscorlib.
UseLocalProxies	Boolean	true
If true, JSILc will automatically scan each translated assembly for Proxies to apply during the translation process. If false, only Proxy libraries loaded explicitly using the Proxies setting (below, in Assembly Settings) will be used.
ProxyWarnings	Boolean	false
If true, JSILc will output diagnostic information at the end of each translation, listing specific proxies and proxy members that were never used. This can help you identify proxies that were written incorrectly (typos, etc.)
UseSymbols	Boolean	true
If true, JSILc will search for .pdb/.mdb symbols for each loaded assembly, and use variable names from the symbols to improve the quality of the output JavaScript.
UseThreads	Boolean	true
If true, JSILc will attempt to use multiple threads for translation. This typically provides a 25-50% speedup per-core when decompiling .NET assemblies and optimizing output JavaScript. Note, however, that this may increase memory usage or cause you to hit bugs in the compiler, so you may wish to try turning it off if you run into problems.
FilenameEscapeRegex	String	null
If specified, any characters matching this regex in output filenames will be replaced with underscores.

Assembly Settings

The assembly settings are stored as a nested JSON dictionary, with the following options:

Key	Type	Default Value
Ignored	Array of Strings	[]
Specifies one or more regular expressions to apply to the filename and/or assembly name of all assemblies translated. If a match is found, that assembly is completely ignored during translation.
Proxies	Array of Strings	[]
Specifies the location of one or more Proxy Assemblies to apply when translating your application.
Stubbed	Array of Strings	[]
Specifies one or more regular expressions to apply to the filename and/or assembly name of all assemblies translated. If a match is found, code will not be generated for that assembly's methods; only type information and external method signatures will be produced.
Redirects	Dictionary	{}
Specifies one or more regular expressions to apply to the filename and/or assembly name of assembly references contained within translated assemblies. If a match is found, the assembly reference is redirected to point at the value associated with that dictionary key. For example: "Redirects": { "mscorlib" : "mscorlib, Version=4.0.0.0" } This particular configuration dictionary redirects all assembly references matching the regex 'mscorlib' (probably too general, actually!) to specifically load version 4.0 of mscorlib. You could use this to replace v2/v3 mscorlib references in an older .NET application. This feature can also be used to redirect an assembly reference to an entirely different assembly; for example, redirect Microsoft's mscorlib to a copy of Mono's mscorlib. Whether or not this will actually work correctly is a great question...

Code Generator Settings

The code generator has a number of passes with specific purposes. By default, most of them are enabled, but if your application is having strange issues, disabling one of these passes may fix it. If a problem in your application goes away when you disable any of these passes, please report an Issue! Note that disabling a code generation pass may break some applications because certain passes are required for working JavaScript to be produced. There are also experimental passes available that you can opt into by enabling them in the configuration. These experimental passes are off by default because they are not production ready or have downsides that make them a poor choice for all applications. The settings are stored as a nested JSON dictionary, with the following options:

Key	Type	Default Value
CacheMethodSignatures	Boolean	true
This pass generates cached method signatures. Cached method signatures look like $sig.get(xxxx, and are used to speed up overloaded method calls.
CacheTypeExpressions	Boolean	true
This pass generates cached type expressions. Cached type expressions look like $Txx() and are used to eliminate the overhead of resolving type identifiers (since JavaScript runtimes have to walk through the object model every time you reference a type by name explicitly). Cached expressions also eliminate most of the overhead caused by constructing generic types (the equivalent of Foo<int> produces JavaScript that must call a method to pass in the type arguments.)
EliminateRedundantControlFlow	Boolean	true
This pass is primarily responsible for eliminating break, continue and goto statements that cannot possibly be reached within a given function during normal execution.
EliminateStructCopies	Boolean	true
This pass tries to eliminate struct copies that can be statically proven to be unnecessary, because the struct is not modified.
EliminateTemporaries	Boolean	true
This pass eliminates temporary local variables by performing a static analysis of your program. This produces smaller javascript that tends to be more readable and can sometimes improve performance as well.
EliminatePointlessFinallyBlocks	Boolean	true
This pass identifies cases where a try/finally block is unnecessary because the code within the finally block can be proven to do absolutely nothing. This is useful because many IDisposable objects in the .NET framework end up having empty Dispose methods, and try/finally blocks are incredibly expensive in modern JavaScript runtimes.
EmitAllParameterNames	Boolean	false
If "true" will include in translation parameter names for all method/constructors.
SimplifyLoops	Boolean	true
This pass attempts to convert the while loops contained in raw .NET IL back into for and do loops that better match the original C#.
SimplifyOperators	Boolean	true
This pass attempts to simplify redundant binary and unary expressions (for example, by turning !!!false into !false. This pass is also responsible for converting certain operators into method calls and certain method calls into operators, because I am a terrible human being.
PreferAccessorMethods	Boolean	true
This pass converts uses of properties into direct invocations of their get/set methods. This significantly improves perfomrance in most JavaScript runtimes, because they are unable to optimize code that uses properties. This pass may significantly reduce the readability of output JavaScript.
HintIntegerArithmetic	Boolean	true
This pass identifies arithmetic that is intended to produce signed or unsigned integers (instead of floats) and wraps those expressions with type hints. Type hints enable JavaScript runtimes to eliminate overflow checks at runtime and ensure that values always remain as integers, improving performance. This pass may reduce the readability of output JavaScript.
FreezeImmutableObjects	Boolean	false
This pass generates code that can call Object.freeze() inside the constructor for types that only contain readonly fields. The code is disabled by default at runtime. This option is off by default because Object.freeze() and Object.seal() still cause a performance hit in modern JavaScript runtimes.
EnableUnsafeCode	Boolean	false
This pass enables experimental support for unsafe code. This may cause methods that should have been ignored (due to their use of pointers) to instead be translated into broken JavaScript or may even cause the compiler to crash.

Solution Builder Settings

The solution builder is responsible for building any .sln files passed to JSILc on the command line and producing a list of the project's outputs. The solution builder settings are stored as a nested JSON dictionary, with the following options:

Key	Type	Default Value	Description
Configuration	String	MSBuild default	Specifies the specific configuration of your solution(s) to build.
Platform	String	MSBuild default	Specifies the specific platform of your solution(s) to build.
Target	String	Build	Specifies the specific target of your solution(s) to build. Meaningful choices are probably Build and Rebuild
LogVerbosity	String	Quiet	Specifies the verbosity of MSBuild log messages. Adjusting this can be useful when troubleshooting problems with MSBuild. Valid options are Quiet, Minimal, Normal, Detailed, and Diagnostic.

## Analyzer Settings JSIL can use different code-analyzers plugins. This section should be used to provide settings for this plugins. Currently the only analyzer plugin is dead code elimination (DCE). It is included in default JSIL build, but is deactivated through this config.

Key	Type	Default Value	Description
DeadCodeAnalyzer	Dictionary	null	Contains DCE plugin settings. See DCE Settings section below.

### DCE Settings Dead code elimination, when activated, use every assembly staring point as start point of processing. Using it can greatly decrease translated assemblies size. Keep in mind, that DCE will include only statistic reachable code to output - so you probably should add some information to white list if you use Reflection or custom implementation of methods on JS side. DCE understand JSExternal, JSIgnore and JSReplace attributes and will stop processing of any member marked with such attribute. Currently DCE cannot process custom method realization provided though JSIL proxies mechanics and will process original method instead. Besides of assembly entry points and specified white list, DCE will process members marked with JSDeadCodeEleminationEntryPoint, any member in class marked with JSDeadCodeEleminationClassEntryPoint and any member declared in class that inherits class marked with JSDeadCodeEleminationHierarchyEntryPoint.

Key	Type	Default Value
DeadCodeElimination	Boolean	false
Specifies, if DCE should be activated.
WhiteList	Array of Strings	[]
Each string specifies regexp to detect if member should be processed as starting point for DCE. Default format for function is: ReturnType DeclaredType::MethodName(Arg1Type,Arg2Type,...). Type names are fully qualified. So, for example for including method with name SomeMethod defined in My.Own.Namespace.SampleClass and returning void, use next regexp: System\\.Void My\\.Own\\.Namespace\\.SampleClass::SomeMethod\\(\\)
NonAggressiveVirtualMethodElimination	Boolean	false
Disable aggressive eliminating of virtual methods. Changing value to `true` will speed up DCE processing a little bit and will preserve virtual method implementation in all types even if it was called only on one type.