This tutorial requires the version 1.0 Beta 11 (or newer) of C#/XAML for HTML5
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 have stopped supporting it long ago, and FireFox has also stopped supporting it in March 2017.
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.
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".
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.
Therefore, the general idea for migrating a Silverlight application into cross-platform HTML5 is the following:
You start by creating a new empty "CSHTML5 Project",
You then copy all your C#/XAML files from your Silverlight project into the new CSHTML5 project,
You then patch the code until it compiles and runs fine,
Keep reading for more information and a detailed tutorial.
This approach has several benefits:
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
Assuming that you have already downloaded and installed CSHTML5, the main steps to migrate a Silverlight application are the following:
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".
In this tutorial, let's assume that you have given the following name to your new CSHTML5 projects: "MyApplication.Cshtml5" and "MyClassLibrary.Cshtml5".
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".
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.
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
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
- 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.
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:
- 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.
To deploy your application, you have many choices:
A major new version of CSHTML5 is released every 8 to 12 weeks, and intermediary "preview" builds are released every 1 to 4 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 roadmap for details.
Late 2017: focus on performance, optimization, reliability, and partial support for 3rd party components (including Telerik, DevExpress, Infragistics, SyncFusion, ComponentOne, and more).
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").
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.
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 firstname.lastname@example.org . 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 email@example.com
To contact the CSHTML5 team for any other reason, please send an email to firstname.lastname@example.org
Learn more: About the Silverlight Migration Edition