Port the Personal Web Site Starter Kit to Tomcat

This is a showcase review for our sponsors at The Code Project. These reviews are intended to provide you with information on products and services that we consider useful and of value to developers.

Microsoft's® .NET 2.0 Framework introduced numerous higher level features on top of the technical underpinnings that made .NET 1.x a success. Improved language features such as C# generics and nullable types and a broader ASP.NET Framework enable you to rapidly develop multi-tier Web sites. ASP.NET 2.0 introduced numerous new Web controls to reduce the amount of C# or Visual Basic code you need to build a Web site. You can use an improved security model, improved and expanded data support, and features such as master pages to build and maintain your Web sites much easier than before.

Grasshopper 2.0 (a.k.a. Mainsoft for Java EE, Developer Edition) introduces support for Microsoft's Visual Studio® 2005 IDE and the .NET Framework 2.0. You can use Grasshopper 2.0 to test cross-platform development, including debugging, using the latest version of Visual Studio software, C# and Visual Basic 2.0 features, and ASP.NET 2.0 controls. You can also rehost existing ASP.NET applications that use the new 2.0 features on Java-enabled platforms with the Tomcat application server, and run the applications under Linux.

How to Get It

Download Grasshopper 2.0, run the executable file, and follow the installation instructions. You can install this side-by-side on a machine that has Grasshopper version 1.x installed.

Please note the following system prerequisites:

• Operating System: Windows XP SP2, Windows 2003 Server, or Windows Vista Ultimate or Business
  Note:
  In order to work with Grasshopper on Windows Vista, you must launch the Visual Studio IDE from an administrator command prompt and launch Tomcat application server as an administrator.

• Visual Studio .NET 2005 Service Pack 1, Standard or Professional editions

Figure 1. New Project dialog

Getting Started with Visual Studio 2005, .NET 2.0 and Grasshopper 2.0

Once you've installed Grasshopper 2.0, launch the Visual Studio 2005 IDE.

Then, choose New Project from the File menu and the New Project dialog appears. See Figure 1.

Check out the project types on the left of this dialog, and you'll see Visual Basic for Java EE and C# for Java EE as supported project types. From here, you can select new project types such as an ASP.NET Web application. Grasshopper 2.0 supports Web applications, Web services, Web controls libraries, console applications and class libraries.

Figure 2. Visual Studio workspace

Once you've created your Web application, you'll see the familiar Visual Studio 2005 workspace, which you can use to design your Web Form applications as you typically would. (See Figure 2.)

The application shown in Figure 2 is a simple Hello one. Use the Visual Studio Toolbox to drag a TextBox control, a Button control, and a Label control onto the Default.aspx design surface. Double-click the button, and the code editor will appear. This allows you to specify the code to run in order to handle the button click event. Change the function's code to read like this:

protected void Button1_Click(object sender, EventArgs e)
{
    Label1.Text = "Hello " + TextBox1.Text;
}

Figure 3. Application running on Tomcat

When the button is pressed, the Label1 label reads "Hello " followed by whatever name is typed into the text box.

The high level of productivity you expect from the Visual Studio development environment is available to you as a cross-platform developer, including full IntelliSense, a cross-platform debugger, and an integrated help system.

Once you've installed Grasshopper 2.0, you'll find an entry in your Start menu, under the Mainsoft for Java EE group, that you can use to launch Tomcat. Tomcat will launch in a DOS prompt window. When it is fully loaded, you may build, run, and debug your application.

Now, press CTRL-F5 to run the application and you can see your application running on Tomcat. It's that easy! You can see this in Figure 3. Note that the application is running on port 8090.

Using the Personal Web Site Starter Kit

The Personal Web Site Starter Kit (PWS) is an application developed by Microsoft to showcase the .NET Framework 2.0 and ASP.NET 2.0 features. It is available for download from MSDN and offers a complete, ready-to-run, and customizable interactive Web site for sharing photos, resumes, and more. This application uses many of the new ASP.NET 2.0 technologies and controls including ASP.NET authentication, the LoginView control, site-based navigation, auto-generated menus, ObjectDataSource, and more.

This article shows you how to port the .NET PWS application to Java. The ported application is also available at <mainsoft_install_dir>\Samples\{CS|VB}\PWS.

One example of a new ASP.NET 2.0 feature that PWS uses extensively is the concept of Master Pages. With a Master Page you design and specify the look and feel of your page and give this the .master file extension. Using the object-oriented methodology, you can then derive other pages from this master and inherit all styling and layout from the Master Page. So if, for example, you take a look at Albums.aspx, you'll see that there is a lot less markup on the page than you'd usually expect. This is because most of the markup that it uses is on the Master Page, and it inherits it because of the reference to the Master Page in the page declaration:

<%@ Page Language="C#" MasterPageFile="~/Default.master"
    Title="Your Name Here | Albums" CodeFile="Albums.aspx.cs"
    Inherits="Albums_aspx" %>

A full discussion of the Personal Web Site Starter Kit, including a complete technology discussion can be found on MSDN here.

Figure 4. Creating the Personal Web Site

In the next few sections, you'll see how to prepare your environment for rehosting this application on Java-enabled platforms, and then you'll go through the simple steps to rehost it.

Step 1: Use the Personal Web Site Starter Kit

Download the PWS from Microsoft here. Once you've installed it, you can create a new Personal Web Site using the template provided with the installation of Visual Studio. To do this, select File > New > Web Site, and you'll see the template for Personal Web Site Starter Kit. Select it, and specify the directory where you want the Web site to be created, and set the language to C# (Visual Basic is also supported). See Figure 4. The IDE will then create the Web site for you in the specified directory, and it can be run on the Cassini Web server by pressing F5. You can see it in action in Figure 5.

Figure 5. Personal Web site running on Cassini

Step 2: Convert the Web Site into a Grasshopper Web application Project

The PWS created your Web site as a Web site project where you stored all the files on the file system, without an associated project file. For Grasshopper, you'll need a project file, as this is used to handle the compiler directives to cross-compile your MSIL code into Java bytecode. Thus, you will need to convert your Web site into a Web application project, leveraging the Web application project type released with Visual Studio 2005 Service Pack 1.

Add a new C# for Java EE Web application project (Figure 6) to the solution, and delete its Default.aspx and Web.Config files. Then select everything from the Web site project and drag-and-drop it into the new project (Figure 7).

After Visual Studio is done inserting the files into the new project, right-click the new project and select: Convert to Web Application. Wait for Visual Studio to complete the conversion.

Now... in a perfect world, your new Web application project should have been ready to build. However, attempting to build your project will yield the following error message: Name 'PhotoManager' is not declared.

For some reason, the Visual Studio conversion tags the application source files to be content files rather than source files that require compilation. Fixing the problem is actually easy. All you need to do is to select all the files under the Old_App_Code folder in the new project and change their Build Action property from Content to Compile (Figure 8).

Now, you should be able to build the new project with no errors. In fact, you no longer need the original Web site in your solution, and you can safely remove it. After doing so, you should be left with a single project under this solution.

For more information on migrating Web site projects to Web application projects, see this MSDN article: "Walkthrough: Converting a Web Site Project to a Web Application Project in Visual Studio 2005."

Figure 6. Creating a Grasshopper Web project

Figure 7. Copy files to Grasshopper Web project

Figure 8. Set Build Action to Compile

Step 3: Configure the Application Database

The original .NET Web application used an in-process database, stored in the personal.mdf file, which is located in the App_Data folder.

Figure 9. SQL Express Protocols in Computer Management

Java applications can use the Microsoft JDBC driver to connect to SQL Server Express. However, the MS SQL Server JDBC driver does not provide a way to connect to an embedded database such as the one used by the Web site application.

In reality, due to performance, scalability and robustness considerations, real world Web applications would not typically use embedded databases. Instead, they would use a database managed by a commercial database server such as SQL Server.

Now we need to modify the ported .NET application and switch from an embedded database to an out-of-process SQL Server Express database.

Your ported application will be a 100% pure Java bytecode application at runtime and will use the Microsoft SQL Server JDBC drivers for database connectivity.

First, ensure that your SQL Server Express database is accessible via TCP/IP and that it supports mixed-mode authentication.

To do this, use the Computer Management application in the Control Panel > Administrative Tools. Find the Protocols for SQL Express entry, under Services and Applications > SQL Server Configuration Manager > SQL Server 2005 Network Configuration. It should look like Figure 9.

Make sure that TCP/IP is Enabled. You can do this by double-clicking its entry on the right-hand side of the screen, and enabling it on the Protocol tab.

The Grasshopper runtime relies on the Microsoft JDBC driver to connect to SQL Server Express and therefore requires the SQL Server authentication to be enabled on the SQL Express instance. Make sure that the SQL Express instance works in mixed-mode authentication. To do this, you can use Microsoft's SQL Server Management Studio Express (SSMSE) tool, freely available for download from Microsoft.

Launch SSMSE, sign in, select the database and right-click. From the context menu, select Properties. You'll see the SQL Server Properties dialog. Select Security and make sure that the SQL Server and Windows Authentication mode radio button is selected (Figure 10).

Now you have to restart the SQL Express server to allow the change to take effect. You may do this by right-clicking the server name and choosing the option Restart.

Figure 10. Set mixed-mode authentication

NOTE: If you do not restart the server, you will get an error message later on when trying to run the application.

Grasshopper runtime uses the SQL Server Browser Service to connect to SQL Server Express. To make sure that the SQL Server Browser Service is running, launch the Computer Management again, expand Services and Applications, and then click Services. In the list of services, double-click SQL Server Browser, and in the SQL Server Browser Properties window, click Start.

You are now ready to run an initialization script that attaches the sample's Personal.mdf database file to your running instance of SQL Server Express and creates a user (user id: pwsadmin and password: pwsadmin123) as a database owner (dbo). Since Grasshopper does not support Windows authentication, this user will be used in runtime to connect to the database. From a command prompt, run the following commands:

cd <Mainsoft_install_dir>\Samples\{CS|VB}\PWS
sqlcmd -S .\SQLEXPRESS -v PROJECTDIR=
    "<Mainsoft_install_dir>\Samples\{CS|VB}\PWS" -i .\personal.sql

Note: You can safely ignore the following warning:

File activation failure. The physical file name "<path>\Personal_log.LDF" may be incorrect.

Last, set the connection string of the new out-of-process database that you just created. To do this, open the web.config file in your Visual Studio editor, and replace the Personal connection string:

<add name="Personal" 
    connectionString="Data Source=.\SQLExpress;
        Integrated Security=True;
        AttachDBFilename=|DataDirectory|Personal.mdf"
    providerName="System.Data.SqlClient"/>

...with the following:

<add name="Personal" 
    connectionString="Data Source=.\SQLExpress;
        Initial Catalog=personal;
        Integrated Security=false;
        user id=pwsadmin;
        password=pwsadmin123" 
    providerName="System.Data.SqlClient"/>

Step 4: Configure the Application Data Database

ASP.NET 2.0 default membership and role providers use an embedded in-process instance of SQL Server 2005 Express to provide a persistent store for application data such as membership and roles. Grasshopper 2.0 default providers are based on Apache Derby™, which is a pure Java embedded database.

Grasshopper implemented new providers for working with the default Derby database. The Derby providers and the connection string for working with the Derby database are defined in the machine.config file, located inside Grasshopper System.jar file (in <mainsoft_install_dir>\java_refs\framework\System.jar).

Grasshopper runtime will read the connection string for the application data database from the machine.config file. You may delete the LocalSqlServer connection string lines from the Web.Config file:

<remove name="LocalSqlServer"/>
<add name="LocalSqlServer" 
    connectionString="Data Source=.\SQLExpress;
        Integrated Security=True;
        User Instance=True;
        AttachDBFilename=|DataDirectory|aspnetdb.mdf" />

Step 5: Build, Run and Debug the Ported Personal Web Site

Figure 11. Debugging the PWS sample

There is nothing special about building the Java EE project using Grasshopper, and that's what makes Grasshopper so appealing -- if you know how to build a C# project in the Visual Studio development environment, then you know how to build the Java version of it. All you have to do is change the configuration to Debug_Java, and launch the Tomcat application server.

You can press F5 to compile the application into MSIL, cross-compile this MSIL into Java bytecode, deploy the bytecode to Tomcat, and launch it with the Grasshopper debugger:

Your Java EE version of the PWS application looks exactly the same as in .NET, and may be used in the same manner as in .NET. To learn how to use the Personal Web Site you have just ported, read the instructions in the sample's Welcome.html page.

You may test the Grasshopper debugger now (see the debugger in action in Figure 11). Set some breakpoints and see how it works. Debugging with Grasshopper is no different than what you are used to with Visual Studio. You debug your Grasshopper projects at the source level, and may use the debugger's various windows to inspect and troubleshoot your application. Step through the application, examine the Grasshopper stack trace, and expand some objects in the Autos window.

Figure 12. Mainsoft Web Site Administration Tool

Welcome to Java, .NET 2.0 developers!!

Step 6: Configure Users, Roles and Membership

As with the .NET version of the PWS application, you can also configure users, roles, and membership for the Java EE version of the PWS sample. Open the Mainsoft Web Site Administration Tool from the ASP.NET Configuration Project menu of Visual Studio. Look at the address bar and notice that the tool is running on the Tomcat application server, under http://localhost:8090/MyWebsiteProject/aspnetconfig/Default.aspx (Figure 12).

Figure 13. Personal Web site running on Tomcat

Use the Web Site Administration Tool to create and manage users and roles for your Personal Web Site sample. Conclusion

Conclusion

In this article you found how Grasshopper 2.0 can be used to migrate a pretty complex Web application from C# on the Microsoft runtime, to C# on a Java EE runtime, with minimal recoding. In a similar manner, you can rehost .NET 2.0 applications to run on Linux. That's the power of Grasshopper 2.0 and that's just for starters.

So, what do you think?