Contents

Introduction

Setup

FAQ

Troubleshooting

Web Application

Release Notes

Download

 

Language

English

Japanese

 

Info

Home

Home (alt.)

Web Application Development for the DICE

Currently the DICE web server supports 3 kinds of web applications; .NET web applications, Perl CGI execution by embedded Perl interpreter, and ISAPI extensions including PHP 5. This section explains how to write and deploy them.

 

.NET Web Application

1. .NET Application Container

A .NET web application for the DICE is a source code written in C#/VisualBasic.NET/JScript or a compiled .NET assembly. A source code is compiled into a .NET assembly at its first invocation and cached by the DICE.

Unlike traditional web applications such as CGI, a deployed .NET application in the .NET container of the DICE is persistently on-memory in a server-side virtual machine and outputs results of cumulative executions as a web page just like Java Servlet.

"test.cs" in the web folder of the DICE is a sample script in C# to illustrate how to write such an application.

2. Requirements for .NET Web Applications

1) A .NET application for the DICE must refer to the .NET assembly called ManagedAppContainer.dll in the folder where the DICE executable file is located.

2) The entry point to a .NET application for the DICE is a class with the same name as the assembly name without an extension under the namespace of the same name. If your application is a source code Foo.cs, you must provide a class Foo in the namespace Foo.

3) The entry point class must implement the abstract class ManagedAppContainer.Proxy. This abstract class is declared in ManagedAppContainer.dll as


abstract public class Proxy
{
	abstract public void Execute(
		byte[] strEntityBody,
		Hashtable mapEnvironment,
		ref byte[] strRequestParameterAndOutput
	);
}

Your entry point class must inherit from this class and override the method Execute. The DICE invokes this method when a .NET application is invoked from a web browser, and an invoked .NET application returns its result to the DICE via the third parameter of this method, a byte array strRequestParameterAndOutput, then the DICE returns this data to a web browser.

4) The on-demand compilation system can refer to all managed Microsoft assemblies (except for Managed DirectX ones) in Global Assembly Cache (GAC) at the startup of the DICE server.

5) A .NET application for the DICE must output all HTTP headers including HTTP/1.0 200 and Content-Length.

3. Loading .NET Appilication

A C# source code in the web directory of the DICE is compiled at the first time it is requested from the web. It creates a .NET assembly file with the "hidden" file attribute and .dll extension in the same directory. Since the DICE ignores requests from the web to files with the "hidden" attribute, a compiled assembly is invisible to web users while the original URL is still accessible. The produced .NET assembly is then loaded and executed in a discrete AppDomain for each requested URL.

MIME bindings tell the DICE what kind of files are such executable scripts. In the default configuration, files with the extension ".cs" are associated with C#, ".vb" with VisualBasic.NET, and ".jsx" with JScript. Instead of letting the DICE compile a source code, a pre-compiled .NET assembly can be put too (".dll" files).

Once loaded, an instance of the entry point class that was discussed earlier is created and the overridden method Execute is called with parameters that are properties of an HTTP request. An execution error is shown as an error message to the web user who invoked it. Statefull objects such as session are easily implemented as a .NET web application stays in a DICE-hosted CLR unless explicitly unloaded.

4. Unloading .NET Application

To unload your .NET application compiled from a source code by the DICE, the source code of the application has to be removed in the file system from Explorer, then you have to access its URL from the web with a web browser. For a pre-compiled assembly, rename its file name from Explorer then access its URL from the web with a web browser, then delete it with Explorer.

5. Processing Input from Web

When a .NET application is invoked from the web, the Execute method is called.

The first parameter, strEntityBody, is filled with entity body data when it's a POST request. If it's a GET request, its size is 0.

The second parameter, mapEnvironment, passes environmental data. It currently contains only one value with the key REMOTE_ADDR, which is the IP address of the user who invoked it.

The third parameter, strRequestParameterAndOutput, is filled with the HTTP request header lines split with '\n'. You have to parse it by youself. Also, this parameter is used to return the generated page to the user who invoked it. You have to replace this ref parameter with the new byte array that represents the generated page with correct HTTP reply headers.

The sample code test.cs shows how to process GET and POST requests.

(Note: Since the current directory of your .NET application is the DICE application folder, you must provide an absolute path whenever you need to access the file system)

6. Security

Currently a .NET application hosted by the DICE is executed with the same privilege as the DICE itself. This means there's no security barrier to protect your system from a malfunctioning .NET application except for your own skill of writing a secure code. Because of this looseness, you can run ANY kind of applications in the DICE .NET container (contrary to the very word container).

You have to sanitize web input to filter any dangerous things that may cause an arbitrary code to run. Also if your .NET application is statefull it has to be thread-safe. To prevent DoS (denial-of-service) attacks, let your application return a result to the DICE as quick as possible by using techniques such as asynchronus operation whenever possible.

 

Perl CGI Web Application

1. Perl CGI Execution in the DICE

The DICE web server can host a CGI web application written in Perl. As it is executed on-memory once it's loaded in the DICE, it is faster than usual CGI execution. In the default configuration, files with ".pl" and ".cgi" extensions are recognized as Perl CGI.

The Perl embedded in the DICE is the 5.10 development version of which source code is available at the official Perl repository. If you need standard Perl modules for your CGI, download the Perl standard modules pack for the DICE at the download page, then extract it into the perl_lib folder in the DICE application folder.

If you don't want the DICE to load a Perl interpreter, rename or delete PerlShim.dll in the DICE application folder.

2. Requirements of Perl CGI for the DICE

A Content-type HTTP header and the CRLF between HTTP headers and entity body must be printed by a CGI. It doesn't need the shell line in the first line of a script unlike a Unix environment.

The DICE can host a standard Perl CGI application unless it doesn't omit the STDIN handle name in the <> operator that reads lines one by one. Always use it explicitly like <STDIN>.

You have to make sure that your application is secure enough to prevent security problems as it's executed in the same privilege as the DICE itself.

 

ISAPI Extension

1. Setup

The ISAPI (Internet Server Application Programming Interface) extension is a user-supplied binary module to extend the functions of the Microsoft IIS web server. To load an ISAPI extension in the DICE, login to the Web UI as a server administrator then add a mapping for an ISAPI Extension dll to a certain file extension in the server options. Though the DICE can load arbitrary ISAPI extensions that have necessary entry point functions implemented, not all extensions are compatible with the DICE. For example, the DICE can load ASP and ASP.NET ISAPI modules (asp.dll and aspnet_isapi.dll) but they don't run properly. For the current version of the DICE, PHP 5 and ActivePerl are known to work with the DICE. But there's a catch, when you load both of them in the DICE, executing a PHP script crashes the DICE. For now it's the safest option to load a single ISAPI extension in the DICE. Also you have to make sure that your application is secure enough to prevent security problems as it's executed in the same privilege as the DICE itself.

2. Example - PHP

First you have to obtain a Windows binary for PHP. Since support for PHP 4 was discontinued at the end of 2007, you should choose PHP 5. An installer package is better than a zip package since you don't have to manually edit the php.ini configuration file for external modules. Always select "IIS ISAPI module" in the installer. After installation, copy the php.ini file in C:\Program Files\PHP to the DICE application directory. It's the configuration file for PHP and you may edit it with the notepad (In most cases you don't have to edit it). Then add a mapping to the PHP ISAPI extension dll (found as C:\Program Files\PHP\php5isapi.dll in the default installation) in the server settings in the Web UI to make the DICE interpret .php files as PHP scripts.

3. Example - Perl

Perl ISAPI extension can be obtained from ActiveState as a part of ActivePerl. After installation of ActivePerl, login to the DICE web UI as an administrator and associate perlis.dll in the bin folder under the Perl installation folder with extensions such as cgi or pl.

When you write a script for Perl ISAPI, note that you should not output HTTP headers in the script side. It doesn't need the shell line in the first line of a script unlike a Unix environment. As for the error log, PerlIS-Err.log is created in the bin folder of Perl.