Passing JavaScript Objects to Managed Code
Microsoft Silverlight will reach end of support after October 2021. Learn more.
If the target managed property or input parameter is strongly typed (that is, not typed as an object), Silverlight attempts to convert the JavaScript object to the corresponding .NET Framework object. If the conversion fails (because of mismatched types or overflows), an exception is returned to the JavaScript caller.
Type conversions are described in the following sections:
Primitive Types
Well-Known Types
Complex Types
Array and List Types
Dictionaries and Custom Types
.gif "Note") Note: |
|---|
|
.png "Silverlight for Windows Phone"){kind=icon}
Silverlight for Windows Phone does not support the HTML Bridge feature.
Primitive Types
Primitive JavaScript types are converted to their best-match counterparts in the .NET Framework. In the list below, an asterisk (*) indicates that this rule also applies to return values from the GetProperty, Invoke, and InvokeSelf methods.
JavaScript strings* are converted to .NET Framework strings. They can be automatically converted to Type objects if the target input parameter on a scriptable method is typed as Type.
JavaScript null values* are passed as null values.
JavaScript Boolean values* are converted to .NET Framework Boolean values.
JavaScript Date objects* are converted to .NET Framework DateTime objects using UTC times when the target input parameter or property is explicitly typed as DateTime. When JavaScript Date objects are obtained by using the loosely typed ScriptObject methods, the JavaScript Date object is returned as a ScriptObject. In this scenario, you can use the static ConvertToDateTime helper method on ScriptObject to explicitly convert to a DateTime.
JavaScript strings can be converted to .NET Framework DateTime properties or input parameters automatically, by using the Parse class.
JavaScript numbers* can be automatically converted to a conforming target .NET Framework types (numeric type, one of the byte types, enumeration, or string). If the JavaScript number cannot be converted successfully, an exception is returned to the JavaScript caller. If the target .NET Framework type is just object, the following "best fit" conversion rule is used:
JavaScript numbers are returned as Double values. Firefox always returns integer values that are greater than 2^31 as doubles, whereas Safari deals only with doubles. The Double return type guarantees the same behavior across browsers. (Note that both JavaScript and the .NET Framework support the IEEE 754 floating-point standard, so a non-integer in JavaScript maps cleanly to the Double data type.) Managed code developers have to explicitly convert the returned double value into an integer. However, as noted in Returning or Passing Managed Types to JavaScript, you must also be aware of the potential loss of precision inherent with the double data type.
JavaScript strings can be automatically converted to .NET Framework properties or input parameters that are typed as Guid. The following pattern must be used: "382c74c3-721d-4f34-80e5-57657b6cbc27".
.NET Framework properties or input parameters typed as object are converted using the following heuristics when marshaling by value to a target .NET Framework property or input parameter:
JavaScript arrays are converted to object[].
JavaScript dictionaries are converted to Dictionary<string,object>.
.NET Framework properties or input parameters that are structures are marshaled by value from a JavaScript object. Only public properties and fields on the target structure are candidates for matching JavaScript properties. If the structure does not have a corresponding public property or field for a JavaScript property, the JavaScript property value is silently ignored. You still have to use createManagedObject or createObject to marshal the JavaScript object to a managed structure. Structures are marshaled between managed code and JavaScript as follows:
Passing a structure from managed code to JavaScript results in by-value behavior. The structure value is explicitly unboxed and copied over to JavaScript.
Passing a JavaScript object to managed code, where the target type is a structure, results in by-value behavior and requires an explicit call to createManagedObject.
Passing a JavaScript object to managed code, where the target type is Object, results in a by-reference handle. This enables both the JavaScript caller and the managed call point to manipulate the same structure.
Well-Known Types
Silverlight handles the following well-known JavaScript objects as special cases and returns them as the appropriate HTML Bridge object reference instead:
References to HTML elements are returned as HtmlElement.
Collections of HTML elements are returned as a ScriptObjectCollection.
References to the containing document are returned as HtmlDocument.
References to HTML objects other than elements or the document are returned as HtmlObject.
Arbitrary JavaScript objects can be returned as ScriptObject references. For information about how to obtain ScriptObject references to arbitrary JavaScript objects, see the sections on arrays and dictionaries later in this topic.
Complex Types
The following table provides conversion information for complex types.
JavaScript variable |
Target .NET Framework type |
Result |
|---|---|---|
JavaScript array/dictionary |
.NET Framework array/list type on a [ScriptableMember] property or parameter on a [ScriptableMember] method. |
You must wrap the JavaScript array/dictionary with a call to the create methods and related helper methods to convert it to a managed type. |
JavaScript array/dictionary |
Object on a [ScriptableMember] property or parameter on a [ScriptableMember] method. |
You must wrap the JavaScript array/dictionary with a call to the create methods and related helper methods to convert it to a managed type. |
JavaScript array/dictionary |
ScriptObject. This could be a return value or used as the type for a [ScriptableMember] property or parameter on a [ScriptableMember] method. |
A ScriptObject reference for which ManagedObject is null. |
Array/dictionary interop wrapper |
.NET Framework array/list type on a [ScriptableMember] property or parameter on a [ScriptableMember] method. |
A reference to the concrete underlying .NET Framework type, assuming the type exists in the current application domain. |
Array/dictionary interop wrapper |
Object on a [ScriptableMember] property or parameter on a [ScriptableMember] method. |
A reference to the concrete underlying .NET Framework type, assuming the type exists in the current application domain. You must explicitly cast to get to the underlying type. |
Array/dictionary interop wrapper |
ScriptObject. This could be a return value, or used as the type for a [ScriptableMember] property or parameter on a [ScriptableMember] method. |
A ScriptObject reference on which ManagedObject is non-null. You can cast the ManagedObject property to get to the underlying type, assuming the type exists in the current application domain. |
Array and List Types
The default is explicit by-value marshaling from JavaScript to managed code. Automatic JSON serialization to managed input parameters is not supported. Instead, you must explicitly use creatable types or the create helper methods.
By-Reference Marshaling
You can make a JavaScript array available by reference to managed code in two ways:
The target .NET Framework property or input parameter can be typed as ScriptObject. Managed code can then manipulate the JavaScript array by using the generic get, set, and invoke methods that are exposed from ScriptObject. You can also use the ManagedObject property to get the underlying managed reference.
If the JavaScript array is an array-interop wrapper (see Returning or Passing Managed Types to JavaScript), Silverlight will simply assign the underlying managed array/list reference to a .NET Framework property or input parameter, assuming that the type exists in the current application domain. If you want to round-trip the interop wrapper and have it automatically surfaced with the correct type, you must type the target property or input parameter as the correct .NET Framework type instead of a ScriptObject. If there is a type mismatch between the array-interop wrapper and the target type, an exception is returned to the JavaScript caller.
By-Value Marshaling
If you want to pass a JavaScript array by value to managed code, the target .NET Framework property or input parameter must be typed as something other than ScriptObject. You must then use one of the create or createObject helper methods to explicitly force a conversion from the JavaScript array to a .NET Framework list or array type. This has the effect of disconnecting the JavaScript representation of the data from the .NET Framework representation.
The JavaScript array will be recursively marshaled by value onto the target .NET Framework type. Silverlight will use the JSON serializer to deserialize from a JavaScript array to a conforming .NET Framework array or list type.
Dictionaries and Custom Types
The default is explicit by-value marshaling from JavaScript to managed code. Automatic JSON serialization to managed input parameters is not supported. Instead, you must explicitly use the create or createObject helper methods.
By-Reference Marshaling
You can make a JavaScript dictionary available by reference to managed code by using one of the following two methods:
The target .NET Framework property or input parameter can be typed as ScriptObject. Managed code can then manipulate the JavaScript dictionary by using the generic get, set, and invoke methods that ScriptObject exposes. You can also decide to use the ManagedObject property to get to the underlying managed reference.
If the JavaScript dictionary is actually a dictionary-interop wrapper (see Returning or Passing Managed Types to JavaScript), Silverlight will simply assign the underlying managed dictionary reference to a .NET Framework property or input parameter, assuming that the type exists in the current application domain. If you want to round-trip the interop wrapper and have it automatically surfaced with the correct type, you must type the target property or input parameter as the correct .NET Framework type instead of a ScriptObject. If there is a type mismatch between the dictionary-interop wrapper and the target type, an exception is returned to the JavaScript caller.
By-Value Marshaling
If you want to pass a JavaScript dictionary by value to managed code, the target .NET Framework property or input parameter must be typed as something other than ScriptObject. You must then use one of the create or createObject helper methods to explicitly force a conversion from the JavaScript dictionary to a .NET Framework custom type or dictionary type. This has the effect of disconnecting the JavaScript representation of the data from the .NET Framework representation.
The JavaScript dictionary will be recursively marshaled by value onto the target .NET Framework type. Silverlight will use the JSON serializer to deserialize from a JavaScript dictionary onto a conforming .NET Framework custom type or dictionary.