Limitations and workarounds

Debugger limitations
Design-time limitations and known issues
Build-related limitations
C# and Mscorlib limitations
XAML-related limitations
WCF and HTTP-related limitations
Examples of .NET workarounds

Debugger limitations:

To enable debugging in the Simulator (in C#) using the version 2.x of CSHTML5, please check the options "Suppress JIT optimization on module load (Managed only)" and "Use Managed Compatibility Mode" in the Visual Studio options (menu "Tools" => "Options" => "Debugging" => "General"), as shown in the following screenshot:

Settings to enable debugging

For further debugging tips - including tips for debugging in the browser - please refer to the page "Tips for Debugging".

Design-time 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.

Alternatively, select "Build Only" rather than "Build + IntelliSense" in the "Errors" pane, as shown in the following screenshot (VS 2015 or newer):
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 using CSHTML5 version 2.0 or newer, configuring a WCF Service Reference requires temporarily adding a reference to the "System.dll" assembly. You should add this reference only while configuring the service, and then you should remove it once the service has been configured.
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:
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.

Build-related limitations:

Your CSHTML5 project configuration must be "Debug", not "Release" (this is fixed in version 2.0)

C# and Mscorlib limitations:

You need to rename HashSet<> into HashSet2<> (this is fixed in version 2.0)
The "Decimal" class is not yet supported. Please replace the type "decimal" with another type such as "double". (this is fixed in version 2.0)
Other features that are not yet supported include (many of these are fixed in version 2.0):
- 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)
System.Buffer.BlockCopy (please use System.Array.Copy instead)

(this is fixed in version 2.0) There is currently a limitation to the parameters you can pass to the DataContract and DataMember attributes (will be fixed in version 2.0). 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.
Finalizers, also called destructors, such as ~MyClass, are not supported because there are no finalizers/destructors in JavaScript.
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. (many more mscorlib types and methods will be supported in version 2.0):

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.
ImageBrush is not yet 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 yet.
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.
To style a ComboBox with a custom template or to display non-text elements inside a ComboBox, you need to set the property "UseNativeComboBox" to "False", like this:
<ComboBox UseNativeComboBox="False"/>
Please note that you cannot set this property inside a <Style>, it needs to be set inline (or in C#).
More information on styling a ComboBox can be found here.
Features that are not yet directly supported include:
(Note: an HTML-based workaround may be found for many of the features listed here)
ManipulationMode, ManipulationDelta, ManipulationStarted, ManipulationCompleted, IsFocusEngagementEnabled, implicit data templates, RadiuxX, RadiusY, Slider, TreeView, RTF, StrokeDashCap, LineStackingStrategy, TextBox.LineHeight, XAMLReader.Load, DataContractJsonSerializer (workaround: use the JsonConvert extension), ProgessBar, localizable resx (currently resx are supported but not localizable), {x:Type } syntax (currently supported without curly braces), HttpWebRequest (currently you can use the WebClient class), {x:Static} syntax, AdaptiveTrigger, Data Triggers, EventTrigger, WritableBitmap, client-side EntityFramework support. If you follow this link you will see a list of additional missing features and possible workarounds.

You can accelerate the development of specific features by contributing to the development costs.

You may also be interesed to read the page "List of supported .NET types and methods".

Be sure to vote for your most wanted features on UserVoice.

WCF and HTTP-related limitations:

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

Examples of .NET workarounds:

Limitations	Workaround
SaveFileDialog	Use the SaveFileDialog extension, available at: http://forums.cshtml5.com/viewtopic.php?f=7&t=520
OpenFileDialog	Use the FileOpenDialog extension, available at: http://forums.cshtml5.com/viewtopic.php?f=7&t=522
Application.Current.Host.Content.Resized	Use the "Window.Current.Resized" event instead
Application.UnhandledException	Unhandled exceptions are reported in the browser console window (F12)
GridSplitter.ShowsPreview	Preview is enabled by default
IsolatedStorageFile.GetUserStoreForApplication	Use "IsolatedStorageFile.GetUserStoreForAssembly" instead
DateTime.ToLongTimeString	Concatenate the hours, minutes, and seconds manually
BackEase and ElasticEase	Replace it with one of the supported easing modes: CircleEase, CubicEase, ExponentialEase, QuadraticEase, QuarticEase, QuinticEase, SineEase
Clipboard.ContainsText(...), .GetText(...)	On some browsers, a security limitation prevents websites from reading the content of the clipboard programmatically. A cross-browser workaround is to request the user to press Ctrl+V and intercept the Paste event. Feel free to contact us for assistance.
MouseRightButtonDown	Replace with "MouseRightButtonUp", which is already supported. Feel free to contact us for assistance.