How to integrate CSHTML5 in an existing HTML5 application or ASP.NET

Note: this feature requires v1.0 Beta 13.3 or newer

Introduction

This document contains information on how to integrate code modules written in CSHTML5 in an existing HTML5 SPA.

The general idea is the following:

1. Take the output JS/HTML files produced by compilation of the CSHTML5 project, and copy them into your existing HTML5 or ASP.NET application.

Note: this process can be automated by configuring the "Cshtml5OutputRootPath" in your CSHTML5 project.

2. Replace the default "index.html" with your own file, or delete it altogether.

3. You need to include some <script> tags in your existing application in order to load the libraries used by the CSHTML5 application. You also need to put some JavaScript to initialize the application. You take copy those from the default "index.html" file produced by the compilation of the CSHTML5 application. Please also refer to the sample project provided below for more information.

4. Put a <div> in your HTML page with the ID "cshtml5-root". It will automatically host the root of the XAML visual tree.

5. If you want to integrate multiple XAML views into an existing HTML5 view, it is possible to do so by creating new instances of the "Window" class in XAML, and associating them to specific divs via the "Window.AttachToDomElement" method in C# (see the sample project).

TIP: To create a new Window, you can either do so in C# (var myWindow = new Window()), or you can do so by creating a XAML file with its associated code-behind, such as "MySecondaryWindow.xaml" and "MySecondaryWindow.xaml.cs". To do that, you can use the "UserControl" item template via the "Add" -> "New item..." command when right-clicking the CSHTML5 project in the Solution Explorer, and then manually replace the word "UserControl" with "Window" in both the ".xaml" and the ".xaml.cs" files.

6. You can very easily communicate from your CSHTML5 application to the host HTML5 application by using the C#/JS Interop features.

7. You can also communicate from the host HTML5 application to the CSHTML5 by interacting with the JavaScript objects that are produced by the compilation of the C# objects. Please refer to the sample project for examples.

However, the easiest way is to have your host application expose some sort of internal JS API that the CSHTML5 will consume. This API can also expose some events (or JS methods that take a callback as an argument), and the CSHTML5 application can register to those events or provide C#-based callbacks. To pass a C#-based callback to a JS call, all you have to do is to pass a delegate (such as Action<T>) to the method "Interop.ExecuteJavaScript" described in the C#/JS Interop features page (read the paragraph that says "You can also do it the other way round"). Please feel free to contact us if you have any questions.

Sample Project

The best way to learn how to integrate an CSHTML5 app in an existing HTML5 app is to download the sample Visual Studio project from the following URL (932 KB):

http://cshtml5.com/downloads/IntegratingACshtml5AppInAnSPA.zip

Note: this project requires CSHTML5 v1.0 Beta 13.3 or newer

The solution contains two projects: a CSHTML5 application and an ASP.NET web application that is meant to represent the SPA, even though it is extremely basic in this example.

You can run the WebApplication1 to see it in action.

The source code of the file "index.html" contains many tips about the integration.