The bridge.json file is a global configuration file for a Bridge project and by default is added to the root of your Project.

A very basic bridge.json configuration file would look as follows:

{
  "output": "$(OutDir)/bridge/"
}

The bridge.json file is mapped to the AssemblyInfo class. All settings of the AssemblyInfo class are available to configure within bridge.json.

Including a bridge.json file in your project is not a requirement for the Bridge compiler. If a bridge.json is missing, the compiler will just assume the default values.

Custom bridge.json files

If your project has the default Release and Debug build modes, you can define separate bridge.json files for each build mode, as well as a default bridge.json file for common configs of all build modes.

The config file name is case-sensitive. For example, if the build mode name is Release, the file name must be bridge.Release.json, and not bridge.release.json.

Custom bridge.json files are not limited to Debug and Release build modes. If you have a custom build mode, for example, Staging, just add a bridge.Staging.json file.

Table Of Contents

1. afterBuild
2. beforeBuild
3. buildArguments
4. cleanOutputFolderBeforeBuild
5. cleanOutputFolderBeforeBuildPattern
6. combineLocales
7. combineScripts
8. configuration
9. console
10. defineConstants
11. dependencies
12. fileName
13. fileNameCasing
14. generateDocumentation
15. generateTypeScript
16. html
17. loader
18. locales
19. localesFileName
20. localesOutput
21. logging
22. module
23. namedFunctions
24. output
25. outputBy
26. outputFormatting
27. pluginsPath
28. reflection
29. report
30. resources
31. rules
32. sourceMap
33. startIndexInName
34. useTypedArrays

afterBuild

Type: string

The executable file to be launched after building. You can use absolute or relative paths. A relative path starts with the project's root. An example of usage could be configuring afterBuild to trigger a .bat file to copy the generated JavaScript files to another folder location, such as another web project.

Example

{
  "afterBuild": "Bridge/build/deploy.bat"
}

Sample deploy.bat file.

beforeBuild

Type: string

The executable file to be launched before building. You can use absolute or relative paths. A relative path starts with the project's root. An example of usage could be configuring beforeBuild to trigger a .bat file to remove all files from a directory before compiling.

Example

{
  "beforeBuild": "Bridge/build/clean.bat"
}

Sample clean.bat file.

cleanOutputFolderBeforeBuild

Type: boolean

Cleans up Bridge's output folder before starting to dump built JavaScript files. Defaults to false.

Example

{
  "cleanOutputFolderBeforeBuild": false
}

WARNING: Use with great care. This will recursively erase all files and directories in the output directory!

cleanOutputFolderBeforeBuildPattern

By default, the cleanOutputFolderBeforeBuild config will use the search pattern *.js|*.d.ts to remove files.

The following sample demonstrates how to override the default pattern.

{
  "cleanOutputFolderBeforeBuildPattern": "*myApp*.js|bridge.js|*myApp*.d.ts"
}

WARNING: SERIOUSLY!! Use with great care. This will recursively erase all files and directories in the output directory!

buildArguments

Type: string

Passes extra arguments to the builder (msbuild or xbuild) process.

Example

{
  "buildArguments": "/nologo"
}

combineLocales

Type: boolean

Merges all locale files into a single file instead of individual locale name files (en-US.js for instance). Defaults to false.

Example

{
  "combineLocales": true
}

Note: If combineScripts is used in conjunction with this (combineScripts: true), all the code will be emitted in a single file: locales, Bridge base and Bridge user code. Additionally on this case, the localesFileName setting will be ignored from bridge.json.

combineScripts

Type: boolean

Combines bridge.js and user code in a same file instead of following rules determined by fileNameCasing and outputBy to determine file names. The output file name then will be the project name.

Example

{
  "combineScripts": true
}

Note: This option implies both fileNameCasing and outputBy options will be ignored from bridge.json file.

configuration

Type: string

Override project's 'Configuration' used for paths. By default, this value is queried from the project.

Example

{
  "configuration": "Release"
}

The above example will force to get DLLs from bin/Release/ regardless of current project's selected configuration (Debug for example).

console

Enables global configuration of Bridge Console functionality.

By default, the bridge.console.js file is generated and included in the project output. To disable the Bridge Console, the bridge.console.js file can be removed from your .html file, or by setting "enabled": false.

Example

{
  "console": {
    "enabled": true
  }
}

defineConstants

Type: List<string>

Override project's <DefineConstants> setting/tag in .csproj file. By default, the list is loaded off the .csproj.

Example

{
  "defineConstants": [ "MyConstant1", "MyConstant2" ]
}

dependencies

Type: List<IPluginDependency>

Determines a list of required plugins loaded before building the Bridge.NET project. By default, no plugin is required (empty list).

Example

{
  "dependencies": [
    { "dependencyName": "MyPlugin1", variableName: "MyVar1" },
    { "dependencyName": "MyPlugin2", variableName: "MyVar2" }
  ]
}

namedFunctions

Type: NamedFunctionMode

Creates named function expressions in the emitted JavaScript functions. The default value is None.

Example (bridge.json)

{
  "namedFunctions": "FullName"
}

Example (cs)

public class Program
{
    public void DoSomething()
    {
    }
}

Example (.js)

// If None (default)
DoSomething: function () { }

// If Name
DoSomething: function DoSomething() { }

// If FullName
DoSomething: function Program_DoSomething() { }

Options

NamedFunctionMode includes the following options:

The setting is available in bridge.json and would apply the extra function name to all Methods in the whole assembly. It's an assembly level on or off setting, with an explicit decision to enable. Please see Issue #2407 for more information.

fileName

Type: string

The file name where the JavaScript files are copied to. If omitted, it is [namespace].js by default.

Example

{
  "fileName": "demo.js"
}

You can decorate any class with a [FileName('myClass.js')] attribute. The class script will be generated to the defined file. It supersedes a global fileName setting.

fileNameCasing

Type: string

Sets the filename casing convention used while generating the .js files. Default is CamelCase.

Example

{
  "fileNameCasing": "Lowercase"
}

Options

CamelCase

Groups and converts all filenames by lowerCamelCase.

Example

namespace Demo => demo.js
namespace Demo.Utilities => demo.utilities.js
namespace DemoUtilities => demoUtilities.js

This is the default functionality of Bridge.

Lowercase

Groups and converts all filenames to lowercase.

Example

namespace Demo => demo.js
namespace Demo.Utilities => demo.utilities.js
namespace DemoUtilities => demoutilities.js

None

No case conversion is applied.

Example

namespace Demo => Demo.js
namespace Demo.Utilities => Demo.Utilities.js
namespace DemoUtilities => DemoUtilities.js

generateDocumentation

Type: DocumentationMode

Options to manage the output of JSDoc-compatible documentation in the generated JavaScript and TypeScript definition files. Default is Basic.

Example

{
  "generateDocumentation": "Full"
}

Options

generateTypeScript

Type: boolean

Toggles TypeScript support. If set to true TypeScript definitions (.d.ts) are generated along with the matching JavaScript files. false, by default.

Example

{
  "generateTypeScript": true
}

html

Automatically generate a index.html file and add the file to the output directory.

The html file will be configured by the Bridge compiler to include the JavaScript files for the project.

The index.html can be opened in a browser to run the project.

Options

Example

{
  "html": {
    "disabled": false,
    "title": "My Bridge Demo App"
  }
}

loader

Bridge supports AMD, CommonJS, UMD and ES6 Modules (AMD is default).

The [Module] attribute can be applied to a class or assembly (in this case all classes belonging to the assembly will be included in the module).

The [Module] attribute can accept module type and/or module name. Required module code depends on module type (for example, define method is generated for AMD).

By default, if an application uses a module, Bridge will generate code to load that module (for example, using require method). All modules will be loaded during application startup.

If you want to load modules manually (for example, bundle into one file and manually include in your .html) then module loading can be disabled using the loader config.

See Issue #2217 for additional details.

Example

{
  "loader": {
    "type": "CommonJS",
      "manualLoading": true
  }
}

locales

Type: string

A semicolon-delimited list of locales to emit during Bridge build. Defaults to empty (no locale file emission). Can contain the keyword all or wildcard * (asterisk) to select locales.

Examples

{
  // Include all cultures
  "locales": "all"

  // Include three specific cultures
  "locales": "en-US;pt-BR;ru-RU"

  // Wildcards 
  "locales": "en-*;pt-*"
}

localesFileName

Type: string

When combineLocales is used (combineLocales: true), specifies the filename to which emit localisation scripts. Defaults to Bridge.Locales.js.

Example

{
  "combineLocales": true
  "localesFileName": "locales.js"
}

localesOutput

Type: string

Output folder to locale files' output. Either an absolute path or relative to Bridge's output path.

Example

{
  // A project root folder name
  "localesOutput": "locales"

  // Relative path from the project root
  "localesOutput": "/home/customers/site/js/locales"

  // Full local path anywhere
  "localesOutput": "c:/inetpub/site/js/locales"
}

logging

Add compilation logging to your Project by setting the logging config in the Projects bridge.json file.

The logger will output a tab-delimited bridge.log file with the following fields in each row:

• timestamp (if enabled in config)
• level
• source
• message

The following sample demonstrates adding "Trace" level logging.

Example (bridge.json)

{
  "logging": {
    "level": "Trace"
  }
}

Example (bridge.log)

2017-06-30T20:02:07:847     Trace       Reading define constants...
2017-06-30T20:02:07:854     Trace       Reading define constants done
2017-06-30T20:02:07:860     Trace       Reading project file done
2017-06-30T20:02:07:866     Trace       Inspecting references...
2017-06-30T20:03:47:187     Trace    Bridge    Inspecting references done
2017-06-30T20:03:47:195     Trace    Bridge    Discovering plugins...
2017-06-30T20:03:47:202     Trace    Bridge    Current domain bridge.exe

module

Type: string

The global Module setting. If set up, the entire project is considered as one Module. Though, you are still able to define a Module attribute on the class level.

Example

{
  "module": "MyModule"
}

output

Type: string

The output folder path for generated JavaScript. A non-absolute path is concatenated with the project's root. Absolute paths are also permitted.

Example

{
  // Send to the projects /bin/ folder
  "output": "$(OutDir)/bridge/" 

  // A relative path from Project root
  "output": "../Bridge/output" 

  // An absolute path
  "output": "c:/output" 
}

The following MSBuild properties are supported within output.

outputBy

Type: OutputBy

Options to manage JavaScript output folders and files. Defaults to Project (Namespace before v16.0).

Example

{
  "outputBy": "NamespacePath"
}

Options

OutputBy includes the following options:

outputFormatting

Type: string

Determines whether only formatted, only minified or both versions of the resulting .js files will be output. Default is Both.

Example

{
  "outputFormatting": "Formatted"
}

Options

pluginsPath

Type: string

The folder path to search for translation plug-ins.

A non-absolute path is concatenated with the project's root.

Absolute paths are also permitted, but relative paths will work better cross-platform.

Example

{
  // Folder from project root
  "pluginsPath": "Bridge/plugins"

  // Relative path from project root
  "pluginsPath": "../Bridge/plugins"

  // Unix absolute path
  "pluginsPath": "/home/myUser/projects/Bridge/plugins" 

  // Windows absolute path
  "pluginsPath": "c:/Users/myUser/projects/Bridge/plugins"
}

preserveMemberCase

Removed in Bridge 16.0. Please use the [Convention] Attribute which offers expanded functionality.

reflection

By default, Reflection metadata is automatically generated in a separate .meta.js file.

Generation of the metadata JavaScript file can be disabled by setting disabled to true. For example, adding the following reflection config section to your projects bridge.json file will disable reflection metadata generation.

{
  "reflection": {
    "disabled": true
  }
}

The metadata can be included directly within the projects JavaScript file, instead of a separate file, by setting target to Inline.

Options

report

Type: boolean, string, or object

Dump a build resources' log for your Project by setting the report config in the Project's bridge.json file.

The file will be output by default as bridge.report.log, containing the list of javascript files built and their sizes in human-readable format.

The setting basically accepts a true/false value, a string with the directory or filename to output as, or an object with more details on how the file should be output.

If the providing an object as its parameter, it will accept the following values

Examples (bridge.json)

Dump a bridge.report.log file in the current javascript output directory:

{
  "report": true
}

Create a subdirectory to place the bridge.report.log file:

{
  "report": "reports/"
}

Specify the filename to output the report as:

{
  "report": {
    "enabled": true,
    "fileName": "myreport.log"
  }
}

Example (bridge.report.log)

Resources:
    MyClassFile.js             1.445 KB
    MyProject.js               0.514 KB

resources

The resources config instructs the Bridge compiler to:

1. Control the embedding of resources (what and where).
2. Control the extraction of embedded resources.
3. Specifying the output of file types (*.d.ts and *.js) and exact file names in a certain order- files setting.
4. Combine the items above into one file with a given name. name setting can have # symbol to specify assembly name the resource name should be applied to: "3rdPartyAssembly#script.js"
5. Provide header and footer; A header can be specified either in a special header setting (path to a file or string content) or as the first item within files; if a footer required then it can be the last item in files.
6. Specify a remark for each file. Rendered to the top of each file.
7. Exclude existing resources (for example, locales).
8. Specify if the composed resources are to be saved as a file - extract setting.
9. Specify if output path should be changed (resources.output setting).
10. Existing config option related to output/resources injectScriptToAssembly will be moved into resources section and renamed to inject.
11. If no resources section specified, then the default behaviour is to inject all the output files as Embedded Resources.

Example

{
  "resources": [{
      // A default section (a section with no name setting)
      // Should be one for all resources.
      // 
      // Values defined here will be applied to all resources (if not overridden).

      // Inject the resource into the Assembly
      // as an Embedded Resource. Default is true.
      "inject": true|false,

      // Specifies if a line will be inserted before each file
      // Supports tokens:
      //     {name}
      //     {path}
      //     \n
      // Default is null
      "remark": "// source @{name}\n"
    }, {
      // The resource name
      "name": "bridge.js",
      // It can specify a resource assembly to avoid collisions
      // in case the same name used in several referenced assemblies
      // For example, `script.js` in referenced 3rdPartyAssembly assembly:
      // "name": "3rdPartyAssembly#script.js"

      // A string with a header content 
      // or a path to a file with header content
      // Supports tokens (data taken from assembly version): 
      //     {version}
      //     {date}
      //     {year}
      //     {author}
      //     {copyright}
      "header":  "../header.txt"

      // The resource will be written as a file as well. 
      // Default is true
      // A combination of name + extract (false) + no files
      // means the Embedded Resource is not extracted
      "extract": true|false,

      // If output location should be different
      // than the bridge.json output setting.
      // Works with extract: true setting
      // I.e. providing a way to control the path 
      // the embedded resources being emitted
      "output": "Resources/final",

      // The files to combine
      // A combination of name + files + inject (true)
      // means to compose files into one and inject as Embedded resources.
      "files": [
        "../Resources/misc/header.js",
        "file1.js",
        "subfolder/release.*.js", // use file mask if required
        "end.js",
        "finally.js"
      ]
  }, {
    "name": "bridge.d.ts",
    "files": [
      "../Resources/.typescript/bridge.d.ts"
    ]
  }]
}

The name setting can have # symbol to specify an assembly the resource should be applied to:

// Specifies resource with name `script.js` in referenced 3rdPartyAssembly assembly
`name`: "3rdPartyAssembly#script.js"

// or
`name`: "3rdPartyAssembly#script.css"

The following MSBuild properties are supported by resources.

rules

The rules config allows for refinement of the generated JavaScript syntax created by the Bridge compiler.

Rules that are configured in the bridge.json apply to the whole project. For finer control, such as only applying a Rule to a Class, Property, or Method, please see the [Rules] attribute.

By default, Bridge will manage the generated JavaScript, which at runtime will reproduce the expected .NET runtime result. While this JavaScript will execute efficiently and correctly, the developer may want to adjust the style of the generated syntax to create more of a JavaScript style to the syntax.

For example, creating an Anonymous Type in C# requires that additional meta data be available at runtime which would allow for proper reflection and type checking of results. When Bridge encounters an Anonymous Type, the compiler will generate a complete class definition in JavaScript.

Setting the rules config within your bridge.json files will instruct the Bridge compiler to generate a plain { } JavaScript object when it encounters an Anonymous Type.

Example

A basic C# Anonymous Type:

var config = new { Id = 123 };

The above C# sample will generate the following simplified JavaScript object literal instead of a fully defined anonymous type class.

var config = { Id = 123 };

The following sample demonstrates a block of rules config that can be added to your bridge.json.

// Rules to manage generated JavaScript syntax.
// Default is "Managed".
"rules": {
  "anonymousType": "Plain",
  "arrayIndex": "Managed",
  "autoProperty": "Plain",
  "boxing": "Managed",
  "externalCast": "Plain",
  "inlineComment": "Plain",
  "integer": "Managed",
  "lambda": "Plain"
}

Other Rules are supported, as outlined in the following options.

Options

anonymousType

C#

// C#
var config = new { Id = 123 };

JavaScript

// "Managed"
var config = new $asm.$AnonymousType$1(123);

// "Plain"
var config = { Id: 123 };

arrayIndex

C#

// C#
var arr = new int[1]; 
arr[0] = 1;

JavaScript

// "Managed"
var arr = System.Array.init(1, 0, System.Int32);
arr[System.Array.index(0, arr)] = 1;

// "Plain"
var arr = System.Array.init(1, 0, System.Int32);
arr[0] = 1;

autoProperty

C#

// AutoProperty | "autoProperty"
var app = new Program();
app.Name = "My App";

JavaScript

// "Managed"
// Real js getter & setter are created
app.Name = "My App";

// "Plain"
// Just a plain js field
app.Name = "My App";

boxing

C#

Object o = 5;

JavaScript

// "Managed"
var o = Bridge.box(5, System.Int32);

// "Plain"
var o = 5;

inlineComment

C#

public static void DoSomething()
{
    // Inline comments copied to .js
    var msg = "comment or no comment?";
}

JavaScript

// Managed
DoSomething: function () {
    // Inline comments copied to .js
    var msg = "comment or no comment?";
}

// Plain
DoSomething: function () {
    var msg = "comment or no comment?";
}

integer

C#

var val = 55;

var v1 = (sbyte)val;
var v2 = (byte)val;
var v3 = (char)val;
var v4 = (short)val;
var v5 = (ushort)val;
var v6 = (int)val;
var v7 = (uint)val;
var v8 = (long)val;
var v9 = (ulong)val;

int i = int.MaxValue; 
byte b1 = (byte)i;

JavaScript

// "Managed"
var v1 = Bridge.Int.sxb(val & 255);
var v2 = val & 255;
var v3 = val & 65535;
var v4 = Bridge.Int.sxs(val & 65535);
var v5 = val & 65535;
var v6 = val;
var v7 = val >>> 0;
var v8 = System.Int64(val);
var v9 = Bridge.Int.clipu64(val);

var max = 2147483647;
var j = (max + 1) | 0;

// "Plain"
var v1 = val;
var v2 = val;
var v3 = val;
var v4 = val;
var v5 = val;
var v6 = val;
var v7 = val;
var v8 = val;
var v9 = val;

var max = 2147483647;
var j = max + 1;

lambda

C#

Action a = () => Console.WriteLine("lambda!");

JavaScript

// Managed
// A shared "lifted" function is generated.
var a = $asm.$.Demo.Program.f1;
...
f1: function () {
    System.Console.WriteLine("lambda!");
}

// Plain
// A plain JavaScript function is generated.
var a = function () { 
    System.Console.WriteLine("lambda!");
};

sourceMap

With Bridge you can debug the original C# files directly in a browser by enabling sourceMap support within your projects bridge.json file.

Example

{
  "sourceMap": {
    "enabled": true
  }
}

Using the browsers developer tools, breakpoints can be set and the next time the breakpoint is hit (or page refreshed), the debugger will stop on the breakpoint. The following screencast demonstrates setting a breakpoint and watching a variable.

startIndexInName

Type: int

When outputBy is either ClassPath or NamespacePath, using a value greater than 0 here will crop the resulting file name by the position specified. Default is 0 (full filename output).

Example

{
  "outputBy": "NamespacePath",
  "startIndexInName": "3"
}

If a code is in namespace ClassLibrary1, instead of a classLibrary1.js file, the output file would be named ClassLibrary1.js.

useTypedArrays

Type: bool

When set to true, will map an array to one of its closely corresponding JavaScript Typed Array type. Default is false (do not try to resolve arrays into javascript typed arrays).

Example

var intArray = new int[5];

If useTypedArrays is false, the output will be:

var intArray = System.Array.init(5, 0, System.Int32);

If true, then will output

var intArray = System.Array.init(new Int32Array(5), System.Int32);

More cases, and the expected output when true can be seen in unit tests project 06:

• cs source file
• js result file