Upgrading to Bridge v16

Geoffrey McGill edited this page Aug 21, 2017 · 14 revisions

The Bridge 16 release represents a significant enhancement over previous versions, with 375+ Issues being closed during this milestone release. That includes 86+ new features and 200+ defects being fixed.

Upgrading to Bridge 16 may require some changes to your project. While some changes in v16 are technically Breaking Changes we've tried hard to minimise the scope of the breaking changes. Most only require simple modifications, and many are coordinated with simple configuration settings for bridge.json or Attributes which revert to the previous functionality.

This easy reversion should allow projects to get to successful compilation quickly, then progressively update to the new features as required.

Table Of Contents

  1. Backwards Compatibility Quickstart
  2. Important Issues
  3. Structural Changes
  4. Naming Changes
  5. Functionality Changes

Backwards Compatibility Quickstart

After installing Bridge 16 to an existing Bridge project, such as Bridge v15.7, adding the following settings to your project should provide complete backwards compatibility for most projects. These quick start items should get your project compiling quickly.

The explanations for each of the backwards compatibility settings are described in the sections further down in this document.

IMPORTANT: These items are only suggestions to help to get an older Bridge project compiling in Bridge v16 quickly.

#1. Delete the new bridge.json file if added

If Bridge 16 added a bridge.json file to your project root, and you still have a /Bridge/bridge.json file, delete the new bridge.json file. Bridge will continue to use your existing /Bridge/bridge.json file, but you shouldn't have both (more info).

#2. Add global [Convention] attribute to assembly

All members such as Methods, Properties, and Fields are no longer re-cased in Bridge 16. Previously, member names are converted to lowerCamelCase. With Bridge 16, the original name case is maintained (more info).

You can revert to lowerCamelCase names by adding the following [Convention] attribute into your projects AssemblyInfo.cs file.

[assembly: Convention(Target = ConventionTarget.Member, Notation = Notation.LowerCamelCase)]

#3. Include bridge.console.js into .html page

The Bridge Console functionality has been moved into a separate bridge.console.js file. If you're using Bridge Console, add this file to your .html page. If you are not using Bridge Console, the bridge.console.js file can be ignored (more info).

#4. Bridge.Collections package is not required

The Bridge.Collections functionality has been merged into the main Bridge.Core package. After installing Bridge v16, the Bridge.Collections package can be removed from your project. No other changes should be required (more info).

#5. Add fileNameCasing config to bridge.json

By default, Bridge v16 will now create lowercase file names. To maintain the old lowercase .js file names, add "fileNameCasing": "Lowercase" configuration to your bridge.json file (more info).

{
  "fileNameCasing": "Lowercase"
}

#6. Disable automatic reflection

If you're using the [Reflectable] attribute in your app, disable automatic global reflection metadata generation, then your [Reflectable] attributes will revert to their previous functionality.

With Bridge v16, reflection metadata is now automatically generated and included with a separate [app].meta.js file. You can disable automatic reflection metadata support by adding the following config to bridge.json (more info).

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

IMPORTANT: This document is editable. If you find something missing, please add. If you find a mistake, please fix.

Important Issues

  1. No automatic re-casing of entities #2577
  2. New [Convention] Attribute #2477
  3. Include Reflection metadata by default #2732
  4. Merge Bridge.Collections into main Bridge/System namespace #2730
  5. Refinements to ObjectLiteral attribute #2276
  6. Revise default setting of fileNameCasing to use None #2755
  7. Setting outputBy to be Project by default #2536
  8. Do not $index overloaded extern or [External] methods #2770

List all Breaking Changes.

Structural

No root Bridge folder

In past releases, the default installation process would create a /Bridge folder in the project root. Inside the /Bridge folder, the bridge.json file would be added, and two other subfolders, /Bridge/output and /Bridge/www.

15 7 0 default install

In Bridge v16, the installation process has been significantly cleaned up, and now only one file (bridge.json) is added to your projects root folder location.

16 0 0 default install

New bridge.json default location

The default location of the bridge.json file has moved to the projects root folder.

If you are upgrading an older (pre v16) Bridge project, the previous /Bridge root folder and structure will continue to work with Bridge v16. It is not necessary to move your bridge.json file to the project root, but we do recommend moving an existing bridge.json to the project root as this is the new default location.

New default output location

The Bridge compiler will output the generated JavaScript files to the path set in the output config of your projects bridge.json file.

In past releases, the default output value is set to "Bridge/output".

Example bridge.json (15.7.0)

{
  "output": "Bridge/output"
}
15 7 0 all files

In Bridge v16, the default output value has been updated to "$(OutDir)/bridge/". This new path will output the generated files into your projects /bin/Debug/bridge/ folder if compiling in Debug mode or /bin/Release/bridge/ if compiling in Release mode.

Example bridge.json (16.0.0)

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

The $(OutDir) path is the same location your project .dll files are added. This is typically the projects bin folder.

The bin folder holds the binary files for your compiled project. These are your executable files. Using the native .NET compiler, the executable files are typically files using the .dll extension. Using the Bridge compiler, the executable files are JavaScript files with a .js file extension.

PROTIP: Bridge now supports using MSBuild macros such as $OutDir and $OutputPath within bridge.json. See Issue #2227 for more info.

Browsing to your projects /bin location using the file explorer or Visual Studio Solution Explorer will reveal the new /bin/Debug/bridge folder and all newly generated files.

16 0 0 all files

PROTIP: Click the Show All Files button in the Visual Studio Solution Explorer panel to show the hidden generated files.

show all files

New index.html file in output folder

In previous releases, Bridge would add a sample demo.html file to the /Bridge/www/ folder. The demo.html was a static file (not auto-generated) and would have to be manually updated if file names changed or new JavaScript files were required.

With Bridge 16, a new index.html file is auto-generated and added to the output location. The same location your projects JavaScript files are created.

The index.html file includes all the JavaScript (.js) files required for the project and added in the proper order.

Example

<!DOCTYPE html>

<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta charset="utf-8" />
    <title>Demo</title>
    
    <script src="bridge.js"></script>
    <script src="bridge.console.js"></script>
    <script src="bridge.meta.js"></script>
    <script src="Demo.js"></script>
    <script src="Demo.meta.js"></script>
</head>
<body>
</body>
</html>

The index.html is regenerated upon each new commit. If you manually make revisions to this file, the changes will are overwritten with the next compile.

You can disable the index.html generation by configuring the html setting in your projects bridge.json file. The following bridge.json snippet demonstrates setting the html config to disable the index.html generation.

Example

{
  "html": {
    "disabled": true
  }
}

Bridge.Collections now in Bridge

The Bridge.Collections project has been merged directly into the main Bridge project. Separately referencing this package is no longer required. See Issue #2730 for more info.

Other than removing the Bridge.Collections package from your project, no other changes should be required. The classes are still within the same namespace, the API is the same, and no calling code would need to be updated. Just remove the Bridge.Collections package.

Naming

File name case unchanged unless specified

With the index.html sample above, you might have noticed the app .js file is named Demo.js, where in previously this file would have been created as demo.js. Uppercase Demo.js vs lowercase demo.js.

With Bridge 16, file names are not re-cased. By default, the Project name is used as the filename. The default [fileNameCasing] config is now set to None. See Issue #2755 for more info.

You can easily revert to the previous functionality by setting the [fileNameCasing] config to Lowercase in your projects bridge.json file. The following sample demonstrates setting the fileNameCasing config.

Example

{
  "fileNameCasing": "Lowercase"
}

PROTIP: The file name can also be explicitly set by adding the [FileName] attribute to your project.

No automatic re-casing of anything

As of Bridge 16.0, and by default, the Bridge compiler will no longer automatically re-case any entity names to lowerCamelCase. This includes Namespaces, Classes, Methods, Properties, or Fields. See Issue #2477 for more info.

For example, if your method name in C# is DoSomething(), the Bridge v16 compiler will create a function called DoSomething() in the generated JavaScript. Previously, a function called doSomething() would have been created.

You can bring back the old behaviour and have fine-grained control over the re-casing of member names by using the [Convention] attribute.

To revert the previous functionality of using lowerCamelCase for member names (Methods, Properties, and Fields), add the following [assembly: Convention] attribute somewhere within your project. A good place to add the attribute is to the projects AssemblyInfo.cs file.

[assembly: Convention(Target = ConventionTarget.Member, Notation = Notation.LowerCamelCase)]

Bridge Console optional

Bridge Console is now included as a separate bridge.console.js file, instead of being packaged in the main bridge.js as with previous releases. See Issue #1994 for more info.

If you do not require Bridge Console in your app or library, do not include the bridge.console.js in your .html page.

If you have Bridge combine all your .js files into one file by using the "combineScript": true config in your bridge.json, you can force the bridge.console.js to be excluded from the combined file by adding the following "resources" config to your bridge.json.

{
  "resources": [
    {
      "name": "bridge.console.js",
      "extract": false
    }
  ]
}

Functionality

Reflection supported by default

As of Bridge 16.0, reflection metadata is automatically generated and added to a new [app].meta.js file. This file will be added to your output folder location. See Issue #2732 for more info.

In previous releases, the reflection metadata was only generated if the [Reflectable] attribute was added at the Class or Assembly level.

Continueing with our sample Demo project from above, the Bridge 16 compiler will now create a separate Demo.meta.js file in the output folder. This Demo.meta.js file is automatically included in the index.html file.

To revert to the previous functionality (before v16), automatic metadata generation can be disabled by configuring the [reflection] property within your bridge.json file. The following sample demonstrates setting disabled to true.

Example

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

Once reflection is disabled, you can add [Reflectable] attributes to customise metadata generation.

By default, the reflection metadata is added to a separate [app].meta.js file, but the Bridge compiler can emit the metadata inline to your [app].js file by setting the reflection.target config.

Example

{
  "reflection": {
    "target": "Inline"
  }
}

ObjectLiteral refinements

The [ObjectLiteral] attribute has undergone some nice cleanup to its default functionality. See Issue #2276 for more info.

Previously if you wanted your C# object to emit as a plain { key: value } object in JavaScript, the [External] attribute was required in addition to the [ObjectLiteral] attribute.

With Bridge 16, setting the [ObjectLiteral] attribute on a class will create a { key: value } object in the generated JavaScript.

The following sample demonstrates setting the [ObjectLiteral] attribute on a C# class, and the resulting JavaScript generated by the Bridge compiler.

Example

public static void Main()
{
    var person = new Person { Name = "Frank" };
}

[ObjectLiteral]
public class Person
{
    public string Name { get; set; }
}
// JavaScript
var person = { name: "Frank" };

Type information is no longer included with the default [ObjectLiteral] attribute. Setting the attribute to [ObjectLiteral(ObjectCreateMode.Constructor)] will include Type info in the JavaScript.

Overloaded constructors are also supported with [ObjectLiteral(ObjectCreateMode.Constructor)]. By default, only the default class constructor is supported with [ObjectLiteral].

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.