Silverlight Migration Guide

 
This tutorial requires that you download version 1 Beta 10.8 or newer

Table of Contents

- Introduction

- What is "C#/XAML for HTML5" exactly and how does the migration work

- You keep coding in C#/XAML

- Differences between a Silverlight project and a CSHTML5 project

- Main steps for migrating a Silverlight application

- Deploying the produced app

- Topics of interest

- Roadmap

- Who is behind CSHTML5?

- Support

Introduction

If you have a Silverlight application, chances are that you are looking for a way to migrate it to other technologies. In fact, Chrome, Edge, and mobile browsers do not support it, and FireFox has announcement that it will soon stop supporting it.

If your app targets only Windows-based devices, and if deployment is not an issue for you, you may consider migrating your application to WPF or UWP. However, if you want your app to run in the browser, or if you want to reach more platforms, you will likely find C#/XAML for HTML5 a compelling choice.

In fact, C#/XAML for HTML5 is the only solution that lets you reuse most of your SL code, keep coding in a Silverlight-like way, and at the same time generate cross-platform HTML5-based apps. Your apps run on any modern browser, without the user installing any plugins, and you can even package them for deployment on iOS and Android via PhoneGap/Cordova, as well as other devices such as Chromebooks, Macs, and Linux-based devices.

What is "C#/XAML for HTML5" exactly, and how does the migration work

C#/XAML for HTML5 (also called "CSHTML5") is an extension for Visual Studio 2012, 2013, and 2015 that adds a new kind of project to the "New Project" dialog. This new kind of project is called a "CSHTML5 Project".

Screenshot of Silverlight Migration Edition project templates

A CSHTML5 project is very similar to a Silverlight project, in that it contains mainly C# and XAML files. For example, a blank new CSHTML5 project is almost identical to a blank new Silverlight project: it contains App.xaml, App.xaml.cs, MainPage.xaml, and MainPage.xaml.cs.

The main difference between a Silverlight project and a CSHTML5 project is that the Silverlight project outputs a "XAP" file, whereas the CSHTML5 project outputs HTML and JavaScript files.

Therefore, the general idea for migrating a Silverlight application into cross-platform HTML5 is the following:

  1. You start by creating a new empty "CSHTML5 Project",

  2. You then copy all your C#/XAML files from your Silverlight project into the new CSHTML5 project,

  3. You then patch the code until it compiles and runs fine,

  4. And then, every time you build the CSHTML5 project, the compiler generates the final cross-platform HTML and JavaScript files. Those files are auto-generated, so you are not expected to modify them manually (read the section below titled "You keep coding in C#/XAML"). Furthermore, the produced files are self-contained - meaning that they have no dependencies - which means that they can be redistributed very easily, or deployed to any server (read the section below about deployment).

Keep reading for more information and a detailed tutorial.

You keep coding in C#/XAML

With CSHTML5, the transformation of a Silverlight app into HTML5/JavaScript is not a one-time irreversible operation where you would do a one-time transformation of your C#/XAML code into a set of HTML/JS files, then throw away the C#/XAML code, and keep working in HTML/JS. Instead, CSHTML5 allows you to keep working and maintaining your code in C#/XAML. You never need to modify the generated HTML/JS code manually. 

This approach has several benefits:

  • You can keep leveraging the existing C#/XAML/.NET/VS skills of your team members, instead of forcing them to move to other languages, frameworks, and/or IDE.
  • You can share C# code between the client and the server. This is particularly useful for sharing business objects and entities passed between the client and the server. You can share code using the "Add as link" feature of Visual Studio, and write compiler directives to conditionally comment out portions of the code that are not supported in CSHTML5.

    (Tip: you can use the "Add Service Reference" feature of WCF in a CSHTML5 project. If you do that, as mentioned in the WCF Limitations and Tutorials, you need to make sure that:
    - the entities
    serialized or passed between the client and the server have the [DataContract] attribute
    - the service contract has the [XmlSerializerFormat] attribute
    - the client-side bindings/endpoints are set programmatically
    - you implement CORS in case of cross-domain communication)
  • You can keep leveraging the power of the C# and XAML languages (type safety, viewmodels, user controls, generics, datatemplates, async/await, namespaces, accessibility modifiers, exception handling, etc.), a subset of the .NET classes (WCF, Linq, etc.), and the powerful Visual Studio IDE (refactoring, debugging, intellisense, source control, snippets, immediate window, code analysis, etc.). Those languages and tools were designed since the beginning to enable the creation of large-scale enterprise-grade rich applications.
  • You can share C# files between the original Silverlight project and the migrated CSHTML5 project (using the "Add as link" feature of Visual Studio, and compiler directives to specialize portions of the code). This is particularly useful if you would like to keep - at least for a short period of time - both the migrated version AND the original version of your app, in order for example to go to market faster by not having to migrate the whole application at once, or if you want to keep the old application available for a while to at least some kind of users (eg. administrators).

Differences between a Silverlight project and a CSHTML5 project

There are a few differences between a Silverlight project and a CSHTML5 project in terms of supported features. Although CSHTML5 is a mature product and is already being used in production, it still only supports a (large) subset of the Silverlight features. For example, at the moment, you will not be able to use the same 3D rendering API's provided by Silverlight 5 (note: there are JS-based alternatives that can be used in CSHTML5, such as three.js), and neither will you be able to communicate directly with RIA Services (note: you can workaround this limitation by creating SOAP web services - read below for details). Furthermore, due to the fact that a CSHTML5 project can only reference CSHTML5-compatible assemblies - similarly to how a Silverlight project that only reference Silverlight-compatible assemblies -, you will not be able to use 3rd party Silverlight components unless an equivalent CSHTML5-compatible version of the component is made, or an equivalent JavaScript-based library is found (note: with CSHTML5, you can easily call a JS-based library from your C# code). A growing number of 3rd party libraries are being released for CSHTML5.

Note: if you share code between a Silverlight project and a CSHTML5 project - for example using the "Add as link" feature of Visual Studio-, you will find it useful to know that you can specialize portions of the code by using Compiler Directives (also called Preprocessor Directives), like in the following example:

     #if CSHTML5 
        using Windows.UI.Xaml.Controls;
    #else
        using System.Windows.Controls; //Silverlight
    #endif

Main steps for migrating a Silverlight application

Assuming that you have already downloaded and installed CSHTML5, the main steps to migrate a Silverlight application are the following:

  1. Create one project of type "C#/XAML for HTML5 (Silverlight Migration Edition)" for each of the Silverlight projects that you want to migrate.

    For example, if your solution has two projects: "MyApplication" and "MyClassLibrary", you should create two separate new projects: one project of type "(Silverlight Migration Edition) Empty Application", and another project of type "(Silverlight Migration Edition) Empty Class Library".

    Screenshot of Silverlight Migration Edition project templates

    In this tutorial, let's assume that you have given the following name to your new CSHTML5 projects: "MyApplication.Cshtml5" and "MyClassLibrary.Cshtml5".

  2. Make it so that the new projects reference each other in the same way that your Silverlight projects reference each other.

    For example, if "MyApplication" references "MyClassLibrary", you should make it so that "MyApplication.Cshtml5" references "MyClassLibrary.Cshtml5".

  3. Copy/paste all the C#/XAML files contained in your Silverlight projects into the newly-created CSHTML5 projects (with the exception of "App.xaml" and "App.xaml.cs", which you may want to merge manually).

    To ensure that the folders structure is preserved, a technique is to open Windows Explorer, select all the files and folders contained in a project (with the notable exception of the folders "bin", "obj", "Properties", and the files "App.xaml" and "App.xaml.cs", which you may want to merge manually), then copy them to the clipboard (by pressing Ctrl+C), then go to Visual Studio, select the CSHTML5 destination project in the Solution Explorer panel, and press Ctrl+V. This will paste all the files into the selected project, while recreating the folders structure.

    Alternatively, instead of copying the files (which will result in redundant duplicates), you can share the files between the Siverlight projects and the CSHTML5 projects. To do so, you can use the "Add as link" feature of Visual Studio: right-click on the destination CSHTML5 project, click "Add => Existing Item...", browse to the original Silverlight project, select the C# files, and then click "Add as link..." (if you do not know where the "Add as link" button is, look at the screenshots here).
    A few notes though:
     - If you share files, you need to manually recreate the folders structure, because you cannot share entire "folders" in Visual Studio
     - In the current version of CSHTML5, you are encouraged to share C# files, but not to share XAML files, because XAML files do not let you write "compiler directives" to specialize portions of the code, so it may not be practical to adapt the XAML code to CSHTML5 while maintaining compatibility with the original Silverlight XAML code.

  4. Try compiling your CSHTML5 project and fix the code until it compiles properly.

    If your solution contains multiple projects, instead of trying to compile the whole solution at once (which may result in an unmanageable number of errors), it is recommended that you start by attempting to compile only the smallest projects that have no dependencies (ie. the projects that do not reference other projects). Once you are able to compile those projects, you can move on to attempting to compile larger projects or projects that have more dependencies. Usually, you start with the class libraries, and the main application project is the last one that you attempt to compile, after everything else compiles properly.

    As you attempt to compile the projects, you will likely get some errors, some of which can be fixed easily:
    - You can do a find-and-replace in the whole project to replace "Tuple<" with "Tuple2<", and to replace "HashSet<" with "HashSet2<" with "HashSet2<" (this is a limitation of the current version that is expected to be fixed in the future).

    Other incompatibilities may require more work to be fixed. Therefore, if you can temporarily disable a feature that is not supported, or comment out a piece of code that is not compatible, it is strongly recommended that you do so at this stage, in order to move on and to start testing the application as early as possible in the migration process. You can come back to address the issue after every else works fine. For example, if you can initially comment out some ControlTemplates (located in your XAML styles) without loosing core functionality in your application, it is strongly recommended that you do so. In fact, ControlTemplates may use complex animations or visual states that need to be migrated, so it may be a good idea to postpone their migration to a later phase. After you have managed to get your application to run fine, you can come back and uncomment the ControlTemplates one by one.e ControlTemplates one by one.

    If you find yourself in a situation where a feature is not supported, here are some things that you can do:
    - First, see if you can find an easy workaround by replacing the piece of code with another piece of code that leads to the same result
    - Otherwise, if the missing feature is a core .NET feature, you can implement it yourself in JavaScript (because the core .NET features are located in the open-source JSIL libraries that are copied to the output folder) or ask the CSHTML5 community or the CSHTML5 Support to implement it for you.

    If you find yourself in a situation where a feature is missing (such as "DockPanel" in v1.0 Beta 9), instead of changing every piece of code that uses that control, you can add a "fake" class named "DockPanel" (that for example inherits from "StackPanel" and has the same public methods as DockPanel) so that the rest of your code compiles properly. This is a sort of "stub" that is used temporarily to move on in the migration process. The general idea is that, instead of changing the code that requires a missing feature, you can add new classes that will "fake" the said feature. In the implementation of those classes, you can display a message such as MessageBox("This feature is not yet supported");

    If an important feature is missing, such as a 3rd party control, you can either:
    - Implement it in C#/XAML
    - Implement it in JavaScript or use an existing JavaScript library that does the job (see how to call JavaScript from C#)
    - Ask the author of the 3rd party control, or ask the CSHTML5 community, or ask the CSHTML5 Support to implement it for you.

    A few more tips:
    - In the current version, the XAML designer sometimes causes some incorrect errors to be displayed in the Errors panel of Visual Studio. To make sure that you only see the "real" errors, make sure to close all the open XAML designer tabs before compiling the project.
    - It is usually better to fix the XAML errors before fixing the C# errors because the errors displayed for C# files are accurate only after the XAML files compile properly.

  5. After your CSHTML5 project(s) compile properly, you can finally launch the application to ensure that it runs properly.

    At the beginning, you may see some differences in the layout due to the HTML5 rendering engine.

    You can use the Simulator (which appears when you launch the CSHTML5 application) to do step-by-step debugging in your C# code, and you can use the "Inspect Visual Tree" feature of the Simulator to understand where the differences originate from.

    After you have managed to get the application to run fine in the Simulator, you should test it in the web browser. To do so, click the "Run in browser" button that is in the Simulator.

    You can test on different browsers to ensure that the result is the same on all browsers. The browser that has been tested the most with CSHTML5 is Chrome, but other browsers such as Edge, FireFox, and Safari are also supported and should provide the exact same result.

    When first testing in the browser, you may see some differences compared to the Simulator. Those are not supposed to exist, so you should inform the CSHTML5 Support for fixing. In the current version, the most common things that may cause a difference between the result in the Simulator and the result in web browsers are:
    - Client/server communications, WCF, and Serialization: this is due to the fact that the Simulator uses the stack of the real .NET Framework for WCF and Serialization, whereas the web browser uses the stack provided by CSHTML5 (implemented in JavaScript).
    - Linq: some rare features of Linq are not yet supported in the browser. You will see an error in the browser "Console" if you use an unsupported feature.

    If you get any errors while running in web browsers, you can open the Developer Tools of the web browser to read the "Console Log" to see what causes the error. To get more information about a JavaScript error, such as the Stack Trace, which is critical to see the current line of execution in your application code (rather than only seeing the line of JS library code that raised the exception), you should use the "Break on exception" option, as explained in the Tips for debugging JavaScript errors with chrome (the tips are similar for other browsers). A common practice is also to blackbox the JSIL scripts so that, when you do step-by-step debugging in the browser, you only step into your own methods and skip the JS libraries. Also, be sure to read the Common Issues and Solutions page for a list of common JavaScript errors and their solution. If you find other JavaScript errors that do not show up in the Simulator, please contact the CSHTML Support.

Deploying the produced app

The files that are generated by CSHTML5 are plain static HTML and JavaScript files, which means that they have the following features:

  • No dependencies. The files are self-contained. They are made of pure HTML and JavaScript code that does not rely on any frameworks (not even jQuery).
  • Pure client-side. Just like Silverlight, CSHTML5 apps are client-only, meaning that all the code runs on the client machine. Communication with the server is done via web service calls (like in Silverlight). When the client web browser navigates to the place where the HTML/JavaScript files are located, those files are downloaded by the browser into its cache, and the code is executed locally on the client. The produced apps are SPA ("Single Page Application"), which means that there is only one "host" HTML page (though multiple XAML pages may be contained in the app).
  • Static files. No server technology is required to serve the files to the client. There is no need for ASP, PHP, Python, or any other server-side technology. Because the files are pure static HTML/JavaScript files, they can be put on any web server.
  • Compatible with most browsers. The files will run on Chrome, Edge, Firefox, Safari, IE11+, and more.

To deploy your application, you have many choices:

  • Give the HTML and JavaScript files to the end-users. In fact, thanks to the fact that they have no external dependencies, the files can be run even from the local file system, by simply launching the file "index.html" from Windows Explorer without any server at all.

    Note: some browsers, for security reasons, may disable some features - such as Geolocalization or IsolatedStorage - when the files are run from the local file system (ie. when the URL in the browser address bar starts with "file:///..." instead of "http//" or "https://"). During development, this can be easily fixed by uploading the files to a web server, or by using the built-in "Run from localhost" feature of the CSHTML5 Simulator (you will find the "Run from localhost" option by clicking the small arrow located near the "Run in browser" button of the Simulator).
  • Upload the HTML and JavaScript files to a web server and give its URL to the end-users. As mentioned earlier, there are no particular server requirements, because the files are static and have no external dependencies.
  • Package the HTML and JavaScript files into an executable. You can easily make an executable out of your HTML/JavaScript files. You can make executables for Windows, macOS, Linux, and more. For more information, refer to the "Out Of Browser" chapter below.
  • Package the HTML and JavaScript files into an application for iOS (iPhone, iPad, iPod Touch) and Android. To do so, you can use tools such as Apache Cordova or PhoneGap Build (the latter does not require a Mac). More details can be found here.

Topics of interest:

  • Client/server communications
    You can communicate with the server via Web Service calls. CSHTML5 is a client-only technology, similar to Silverlight but without the need for browser plugins. A subset of WCF is supported. You can use the "Add Service Reference" feature of VS to communicate with SOAP web services, or you can use the WebClient control to communicate with REST web services (WebAPI or other). Learn more by reading the WCF Limitations and Tutorials. Alternatively, you can communicate via WebSockets by using the open-source WebSocket extension for CSHTML5
  • RIA Services
    Due to the fact that RIA Services are not supported at this time, you should replace them with standard WCF SOAP service calls (read WCF Limitations and Tutorials). To make the migration easier, a common practice is to create a new server-side project of type "WCF Service Application" that references your server-side RIA Service and functions as an "adapter" (or "bridge") that will relay the communications between your CSHTML5 app and your RIA Service. In other words, instead of communicating directly with the RIA Service, your CSHTML5 application will communicate with your WCF service - which exposes SOAP endpoints -, and the latter will then communicate with your RIA Service via simple method calls (because they run in the same process on the server). Due to the current serialization limitations, we recommend redefining the business entities that are passed between the client and the server if they are too complex or if they have dependencies on EntityFramework (which is currently not supported).
  • DataBinding
    It works exactly as in Silverlight. To see some examples and source code, check out the sample Showcase application (to do so, launch VS, click File => New Project => C#/XAML for HTML5 => Sample Showcase).
  • Styling, Templating, and Custom Templated Controls
    It works exactly as in Silverlight. There are minor differences in the visual states, as mentioned earlier, because Silverlight uses the name "Mouse" whereas CSHTML5 uses the name "Pointer" (same as in UWP apps). Read the Styles and Templates page for examples and limitations.
  • Saving a file to disk
    You can easily save/download a file to the end-user computer by using the open-source FileSaver library for CSHTML5. Some web browsers will display a window similar to the Silverlight SaveFileDialog for choosing the file name and destination folder, while other browsers will simply download the file to the Downloads folder.
  • Opening a file from disk
    You can use the open-source FileOpenDialog library for CSHTML5.
  • Serializing/Deserializing
    You can serialize/deserialize objects using the built-in XmlSerializer class (read XmlSerializer Tutorials and Limitations)
  • Printing
    You can print any UIElement in the visual tree by using the open-source PrintHelper library for CSHTML5.
  • Compressing/Decompressing
    You can use the open-source ZipFile library for CSHTML5, which provides a subset of the functionalities of Ionic.Zip DotNetZip.
  • Out Of Browser support
    Out Of Browser is useful for many reasons, including the ability to run code that requires Elevated Privileges ("Full Trust"), for example to communicate with USB ports, to interact with installed apps (Office Automation/Interop...), to access restricted folders on the File System, and, more generally, to do anything that you are not allowed to do inside the web browser. There are multiple ways to implement Out Of Browser support for CSHTML5 applications. A common way is to take the output HTML/JS files of your application and make a Windows/Mac/Linux executable out of them. You will find many free tools to do that. Alternatively, you can do this manually by following these simple steps: create a new project of type "WPF application", put a web browser control on the MainWindow (you can either use the default IE-based WebBrowser control, which uses the same version of IE that is installed on the end-user machine, or, better, you can use the CEFSharp control which contains an embedded Chromium browser that has no dependencies and that renders the same on all the machines regardless of what web browser is installed) and add some code to the constructor of your MainWindow to make the web browser URL point to your local HTML/JS files generated by your CSHTML5 project. This technique has several benefits, including the ability to move C#/XAML code that requires Elevated Provileges directly into the WPF application, and then to have your CSHTML5 application communicate with the "host" WPF application via simple JS interop calls.

Roadmap

A major new version of CSHTML5 is released every 8 to 12 weeks, and intermediary "preview" builds are released every 1 to 6 weeks. Intermediary builds are usually released on the Pre-Releases section of the forums.

The main milestones in the CSHTML5 roadmap related to Silverlight migration are the following:

  • 2017: the CSHTML5 team works on supporting as many Silverlight features as possible, and attempts to fix all the remaining bugs + initial support for select 3rd party components. See the full roadmapef="roadmap.aspx">full roadmap for details.

  • Q1 2017: the "Silverlight Migration Edition" is updated to make it even easier to migrate Silverlight applications with features such as further improved compatibility with the Silverlight event names ("MouseMove" rather than "PointerMove", etc.), further improved compatibility with the Silverlight Visual State names ("MouseOver" rather than "PointerOver", etc), and more.

  • Late 2017: focus on performance, optimization, reliability, and partial support for 3rd party components (including Telerik, DevExpress, Infragistics, SyncFusion, ComponentOne, and more).

The full roadmap (not limited to Silverlight migration) is available herele here.

Who is behind CSHTML5?

CSHTML5 is made by Userware, a company that has almost 10 years of experience in making developer tools and productivity applications. The company initially gained popularity for applications such as XLS Editor, which was the #1 paid productivity tool in the Windows Store for over 8 consecutive months (in 2014), and WikiOS, a patented experimental online operating system made in Silverlight that could be enhanced Wiki-style by users thanks to an online development environment (the "wikipedia of software").  

CSHTML5 is also powered by JSIL, an open-source Intermediate Language to JavaScript transpiler that has been in development for over 5 years. JSIL has its own team of contributors and has an active community.

A recent version of CSHTML5 has introduced the ability for 3rd parties to create plugins, extensions, and libraries for CSHTML5 to extend its functionality. As the community around CSHTML5 is growing rapidly, it is expected that more and more 3rd party libraries will be released. This will allow the CSHTML5 team to keep focusing on the core engine, while most additional functionality will come from 3rd parties.

The CSHTML5 team has been steadily releasing new versions every few weeks for now more then 2 years, and is expected to continue to do so or even accelerate. The history of the releases in the past several years has shown that the company is able to deliver on what it promises.

The CSHTML5 product already counts thousands of registered users, and hundreds of projects are being developed or migrated from Silverlight.

From a financial point of view, the company is also very healthy and the team is expected to grow significantly in the coming years.

Support

For technical support, please start by posting a message on the CSHTML5 Forums, where the community might be able to assist you. If you do not get an answer quickly, please create a support ticket by sending an email to support@cshtml5.com . Tickets are usually replied to within 24-48 hours. The Support team speaks English, French, and Italian.

To contact the CSHTML5 Sales, please send an email to sales@cshtml5.com

To contact the CSHTML5 team for any other reason, please send an email to hello@cshtml5.com

 

Home | Buy | Documentation | Forums | Contact Us

Learn more: About the Silverlight Migration Edition