Limitations and workarounds

Code editor / designer limitations and known issues:

  • You may sometimes see misleading XAML-related errors at design-time.
    Workaround: to see only the "real" errors, close all the XAML Editor tabs, and recompile your project by clicking the "Build Solution" or "Build Project" commands.
  • When adding a WCF Service Reference (via the "Add Service Reference" command of VS), VS may add unwanted references to your project, such as the "System" reference.
    You need to manually remove those references.
  • When adding a new item to a project, such as a new empty class, VS may add unwanted references to your project - such as the "System" reference - that need to be manually removed.

    Workaround: in the "Add New Item" window, make sure to select the "C#/XAML for HTML5" category on the left instead of the default one, as shown in the following screenshot:

    Screenshot : Add new item
  • Clicking "View Designer" from code-behind will open the WPF XAML editor instead of the CSHTML5 XAML editor.
    Workaround: open the XAML file by double-clicking on it in the Solution Explorer. This will open the correct editor.
  • The XAML Editor is unable to preview custom types and user controls.
    Only native XAML types can be previewed in the XAML Editor at the moment.
  • Ctrl+F will open the "Find in Files" dialog instead of the "Quick Find" pane.

Project limitations:

  • Your CSHTML5 project configuration must be "Debug", not "Release".

C# and Mscorlib limitations:

  • You need to rename HashSet<> into HashSet2<>
  • The "Decimal" class is not yet supported. Please replace the type "decimal" with another type such as "double".
  • Other features that are not yet supported include:
    • Assembly.GetExecutingAssembly (you can workaround this limitation by reading the property "CSHTML5.Internal.StartupAssemblyInfo.StartupAssembly")
    • DateTime.ToLongDateString (please use DateTime.ToString())
    • DateTime.ToLongTimeString (please concatenate the hours, minutes, and seconds manually)
    • Single.TryParse (please use Double.TryParse instead)
  • There is currently a limitation to the parameters you can pass to the DataContract and DataMember attributes. In fact, you can use the DataContract and DataMember attributes normally, but if you need to specify some additional properties, such as the Name in [DataContract(Name="TheName")], it will not work because JSIL is currently unable to retain those properties (it only retains the constructor parameters of the attributes). Therefore, instead, you need to use the "DataContract2" and "DataMember2" classes, and pass the parameters to their constructor, like this: [DataContract2(TheName: "TheName")]. Notice that we use the colons (":") instead of the equal sign ("=") because we are passing constructor named arguments instead of directly setting the properties of the attribute. We are working to fix this limitation. If you need more information, please contact us.
  • Only a subset of the Mscorlib methods are currently supported. You can see the list of supported types here, and read the guide on how to implement mscorlib methods.

XAML-related limitations:

  • The DropShadowEffect is only applied to the element on which it is defined rather than on all its child elements.
    This is due to how the CSS shadow works. In fact, for best performance, we use CSS to render the shadow.
    Workaround: in the XAML file, duplicate the DropShadowEffect to all the children to which you want to apply the effect.
  • CenterX and CenterY are not yet supported in render transforms.
    Workaround: set the RenderTransformOrigin property on the element itself. Tip: to achieve the same transform without using CenterX and CenterY, consider experimenting with Microsoft Blend on a separate WPF or UWP project. In fact, Microsoft Blend by default also does not use the CenterX and CenterY properties for render transforms.
  • Triggers are not yet supported.
    Workaround: instead of Triggers, use the VisualStateManager class in conjunction with Storyboards. Tip: consider experimenting with Microsoft Blend on a separate UWP or Silverlight project, which also do not support triggers.
  • TransformGroup is not yet supported.
    Workaround: instead of a TransformGroup, you may use a CompositeTransform, which lets you apply multiple transforms in the following order: Scale, Skew, Rotate, Translate.
  • ImageBrush is not supported.
    Workaround: use an <Image> control instead. If you need to place the <Image> control behind another control, you can do so by placing both the <Image> control and the said control inside a surrounding <Grid> control. Here is an example of use of the Image control: <Image Source="/AssemblyName;component/FolderName/ImageFileName.jpg" Width="320" Height="240"/>
  • StrokeStartLineCap and StrokeEndLineCap must have the same value for a given element.
    Workaround: set both properties to the same value, or remove those properties altogether. Note: this is due to the fact that HTML5 does not support a different cap for the Start and the End of a line. The default value of those properties is: Flat.
  • ListBox controls do not have built-in scroll bars.
    Workaround: Place the ListBox inside a ScrollViewer control. Tip: for smooth scrolling on mobile devices, set VerticalScrollBarVisibility to Visible rather than Auto.
  • It is recommended that you explicitly set a fixed Width and Height (in pixels) for ChildWindows, otherwise they may take the size of the whole page.
    For example, you can set it like this: <ChildWindow Width="400" Height="400"> ...
  • UpdateLayout is not yet supported.
    This is due to the fact that the UI layout is handled by the browser rendering engine rather than JavaScript. The XAML visual tree in translated into a DOM tree - which is basically a tree of <div> elements - so that the browser can draw the layout with highest performance.
  • Features that are not YET directly supported include:
    (Note: an HTML-based workaround may be found for many of the features listed here)
    UseSystemFocusVisuals, IsFocusEngagementEnabled, IsTabStop, TabIndex, ManipulationMode, ManipulationDelta, ManipulationStarted, ManipulationCompleted, implicit styles, implicit data templates, Generic.xaml, ZIndex, RadiuxX, RadiusY, Frame, Slider, TreeView, RTF, ViewBox, RepeatButton, StrokeDashCap, RadialGradientBrush, LineStackingStrategy, TextBox.LineHeight, CaretBrush, IsFullScreen, XAMLReader.Load.

    Please also refer to the page "List of supported .NET types and methods"..

WCF and HTTP-related limitations:

Click here to read about WCF and HTTP-related limitations.

Related Topics