Why Eucalypto?

My goal is to create a light project that can be used with any ASP.NET compatible environment, without requiring a specific database or additional framework. Eucalypto is composed by a set of .NET assemblies that you must only reference from your project.

Unlike many other similar projects, Eucalypto doesn't have a predefined user interface. Eucalypto is simply a library that can be used from your pages.

Eucalypto is not an all-or-nothing solution. You can use only a subset of the features of Eucalypto. For example, you can use the forum from Eucalypto but continue to use an existing solution for the users and roles. Each feature is isolated. For this reason, it is very easy to integrate Eucalypto in an existing ASP.NET web site.

If configured and used in the right way, I think that Eucalypto is suitable for many situations, especially because it is easy to extend, if required. You can always implement a custom provider implementation, or change the default implementation for your special needs.

Eucalypto uses NHibernate for all the data access; for this reason, you can use a wide range of database servers. See the NHibernate documentation for a list of supported databases.

There are a lot of projects that can be used to create a CMS portal, free or commercial, with similar features of Eucalypto; what are the advantages of Eucalypto?

you can integrate Eucalypto with an existing site or architecture (Web Parts, SharePoint, an existing CMS portal, ...)

you can support advanced or customized user interfaces (accessibility, globalization, WAP, XAML/WPF, AJAX, ...) or use a different presentation layer but the same business layer

you can easily extend/change the business layer (thanks to the provider architecture)

you are not limited by the features of the portal

you can use a wide range of database types (thanks to NHibernate)

there is a clean separation between the presentation layer and the business layer

you can use the full power of ASP.NET and use well know technologies (master pages, themes, user controls, membership, ...)

Appropriate Uses for Eucalypto

Eucalypto uses SQLite as a default database, but thanks to NHibernate, you can configure Eucalypto to use many other databases (SQL Server, MySQL, Oracle, ...). The SQLite database is a perfect solution for a small web site. If you have thousands of users and visits, probably it is better to use another kind of architecture.

Eucalypto must be used by developers, it is not for end users or power users. You must know how to develop an ASP.NET application.

Eucalypto has some important advantages, but also some disadvantages. The most important consideration is that creating a web site with Eucalypto requires some development and configuration. Eucalypto is not a complete web portal, it is a library. You need some time to create a complete and running web site.

If you are looking for a complete portal or a different solution, you can probably try one of these other projects:

Requirements

Currently, Eucalypto is developed using .NET 2.0, Windows, IIS, and SQLite (or SQL Server). Eucalypto is written using 100% managed code, but some references are not compiled as managed library (for example, SQLite).

Probably, using the right database (like MySQL), Eucalypto can be executed also on Linux and Mono, but I have not tested it for now. I don't know if the latest release of NHibernate and Log4net are fully compatible with other platforms, but I hope not to have many problems in the future.

Packages

Eucalypto is composed of two packages:

Eucalypto1 - Main Eucalypto package. Contains the source and binary files for Eucalypto.

Eucalypto - The Eucalypto.dll assembly

Eucalypto.Test - Eucalypto NUnit test assembly

Eucalypto1.Demo - Demo package

WebSite - Demonstration of an ASP.NET website

Demonstration web site

You can also install the demo project on your server if you want to look at the code or modify it. Here are the steps to run the Eucalypto demo project on your server:

download the Eucalypto.Demo package, open it with Visual Studio 2005, and run the WebSite project

open the Setup.aspx page to configure the database and create an administrator user

open the administration page at Admin/Default.aspx for the administrative tasks

Now, you can start to use the Eucalypto demo project. See the following sections if you need more information on the available configurations.

Creating your Website

One common method to start using Eucalypto is to download the Eucalypto.Demo package and use it as a starting point. Eucalypto.Demo contains some useful classes and a working configuration. Here is a short description of the Eucalypto.Demo components:

\web.config - Main configuration file.

\Site.master - Page used for the master page.

\Global.asax - Main application class.

\Controls\*.* - Some common user controls.

\Admin\*.* - Administration pages.

\App_Themes\*.* - Themes, skin, CSS, and images.

\Setup.aspx - Page used to create the database schema (can be removed in the production environment).

Providers Overview

All the base features of Eucalypto are created using a Provider Model pattern (a patter similar to the Inversion Of Control). The Provider Model pattern guarantees easy customization and extensions. If you want, you can create your own providers to save data to another data source, or with a different format, or with special business rules.

Eucalypto.Membership.EucalyptoMembershipProvider - An implementation of System.Web.Security.MembershipProvider.

Eucalypto.Roles.EucalyptoRoleProvider - An implementation of System.Web.Security.RoleProvider.

Eucalypto.Notification.EucalyptoSmtpNotificationProvider - A new provider that can be used to send notifications to users using SMTP and preconfigured e-mail templates. Used by the forum provider to notify users.

Eucalypto.Profile.EucalyptoProfileProvider - An implementation of System.Web.Profile.ProfileProvider.

Eucalypto.Forum.EucalyptoForumProvider - A new provider that can be used to create a complete forum solution.

Eucalypto.Wiki.EucalyptoWikiProvider - A new provider that can be used to insert, update, and retrieve articles.

Eucalypto.News.EucalyptoNewsProvider - A new provider that can be used to manage news.

Each provider is isolated from the other. For example, you can use the forum provider with the Eucalypto database and the membership provider using the default SQL Server database.

Create Database Schema

Now, you must create the Eucalypto database schema. I have written a page, Setup.aspx (inside the WebSiteTest project), that can be used to create the required database schema. You can usually copy this page inside your project and open it with your browser (Note: for security reasons, this page can be executed only from the local server machine).

This page uses the Eucalypto.SchemaGenerator.GenericGenerator class to generate the schema for the selected connection string. You can select the connection string using the drop down at the top of the page (this drop down is loaded with the current connections configured inside the web.config) and then click on the 'Create schema' button to generate the schema.

The Eucalypto.SchemaGenerator.GenericGenerator class uses the NHibernate.Tool.hbm2ddl.SchemaExport code to generate the schema. If you have problems, you can always manually create the database tables.

Remember that for now, this tool cannot upgrade an existing table. If the table already exists, its contents will be deleted.

In the Setup.aspx page, there is also a feature to create the administrative user and role; you must simply choose a new password and click on the 'Create admin user' button.

Administrator Features

I have created a set of pages for the most important administrative tasks. You can copy the Admin folder of the WebSiteTest project inside your website. In this folder, you can find some pages to configure many features of Eucalypto.

Open the Admin/Default.aspx page for an overview of the available configurations. This page requires you to login as an administrator (administrators role), so you must first have correctly configured the user and roles and have created an admin user.

After you have configured the main features, you can start using Eucalypto. See the sections below for the configuration for each feature.

Membership and Roles

The Membership provider is an ASP.NET provider. ASP.NET membership gives you a built-in way to validate and store user credentials, it can be integrated with ASP.NET role management to provide authorization services for your site.

Database diagram

Configuration

To use the membership and role features, you must configure ASP.NET to use the Eucalypto providers, adding this section inside the web.config file:

Please not that for now, the EucalyptoMembershipProvider supports only hashed passwords and do not support the password retrieval feature (EnablePasswordRetrieval), only supports password reset.

Profile

The Profile provider is an ASP.NET provider. You can provide the users of your website with a custom experience by defining and using profile properties. You can use profile properties to track any custom information your application requires.

Database diagram

Configuration

To use the Profile features, you must configure ASP.NET to use the Eucalypto providers, adding this section inside the web.config file:

Use the enabled property to enable or disable the provider. The template property must be configured with a valid XML file that contains the template data used when sending e-mails. Here is an example:

You can use some parameters specified by who will use the notification provider (for example, ?title?, ?user?, ...) that will be replaced by the actual data of the notification. In this case, I have used the parameters used by the forum provider.

Usage

The EucalyptoSmtpNotificationProvider provider can send notification using SMTP (e-mail). You can use the static property Eucalypto.Notification.NotificationManager.Providers to read a list of the configured providers.

Custom Entities

You can extend Eucalypto using custom entities to store additional information for your specific application. Eucalypto exposes a series of classes to simplify the creation and integration of custom entities. In the following sections, you will see how to create a custom Dog entity, complete with the data access class.

Remember that Eucalypto uses NHibernate for all data access, so I usually suggest to first read and understand the NHibernate architecture and code. Eucalypto simply hides some configurations and code, but some experience of NHibernate is important.

The first step is to configure Eucalypto to identify and use your assembly. You can configure Eucalypto by adding a custom section in the configuration file:

As you can see, this is just a standard .NET class, the only required code is the Id property used as the primary key for the entity and a default constructor (public or protected). Compile this class in your assembly. Now, you can create the file that defines the database mapping using the NHibernate configuration file:

You must save this XML in an embedded resource of your assembly with the extension .hbm.xml (for example, Dog.hbm.xml; the .hbm.xml is required by NHibernate). You can usually use any feature of NHibernate (nested classes, collections, inheritance, ...); refer to the NHibernate documentation for more details.

The next step is to create the data access class. Note that you can also use a custom data access class, but using the Eucalypto code can save you some time:

The EntityDataStoreBase is a generic abstract class that can be used for the basic data access features (Insert, Delete, Update, ...). You just need to implement your specific features, usually custom selection and filter.

That's all. Now, you are ready to use your entity. Here is an example of how you can use the custom entity:

Consider that you need a valid connection string (in the example called DefaultDB) and a valid database. See the previous configuration section for more information. If you want, you can also generate the schema of your custom entities using the automatic schema generator; in this case, you need another step to configure the schema generator in this way:

To query or update a SQLite database, I really suggest using SQLite Spy, a very powerful and useful tool. Thanks to Ralf Junker. You can download it from here.

Usually, you can find the SQLite database inside the App_Data directory.

Important notes: SQLite is currently written with C++ as an unmanaged library. For this reason, you must remember that SQLite must be executed with full trust permissions. If you want to use a shared hosting (run your website on a hosting company), you must consider that they are usually configured as medium trust. Medium trust security blocks any P/Invoke code and SQLite cannot run. In this case, you can ask your hosting company to run your app with full trust, or ask to install SQLite library inside GAC. Remember anyway that Eucalypto can be used with many other databases. For example, many hosting companies offer MySQL, Access, or SQL Server.

Log4Net

"log4net is a tool to help the programmer output log statements to a variety of output targets. log4net is a port of the excellent log4j framework to the .NET runtime."

Eucalypto internally uses log4net for logging exceptions and warnings. The entire log4net configuration can be changed in the web.config file. In the global.asax file, I configure Eucalypto with this code: log4net.Config.XmlConfigurator.Configure(). Usually, you can find the log4net log file inside the App_Data directory.

CSS

I hate CSS .... Every time I must work on a page layout, I fight with CSS. For this reason, I always look for some simple and clear examples.

I want to thank Alessandro Fulciniti, for his great work on CSS. For me, these are the most clean and simply to use CSS layouts.

For this site, I have used a modified version of a CSS layout that I have found on the above page.

Provider Model

For more information about the ASP.NET provider model, I suggest you read these MSDN articles:

NUnit

I have created a test project for Eucalypto (Eucalypto.Test) with some test cases. See Eucalytpo.nunit for the NUnit configuration.

HttpModuleCheckValidUser

I have created a custom HttpModule Eucalypto.Membership.HttpModuleCheckValidUser to add an additional security check. Basically, this HTTP module is used to check if a user already authenticated is approved and not locked. This is useful, for example, when a user is automatically authenticated using the "Remember me" cookie.

To use this module, you must add this configuration inside the system.web configuration element:

<!-- Http module to check if the user authenticated
with the Remember me feature is still valid --><httpModules><addtype="Eucalypto.Membership.HttpModuleCheckValidUser, Eucalypto"name="CheckValidUser"/></httpModules>

Improved the security code (SecurityHelper) used to check for permissions for a specific operation on an entity. Now, supports denies permissions for a role using the prefix '!'.

04 Apr 2007 - Version 1.0

Updated references of NHibernate 1.2.0.3001 and SQLite 1.0.40.0.

Added the Eucalypto/Membership/HttpModuleCheckValidUser.cs HttpModule to check if a user is still valid if authenticated with the cookie.

Fixed a bug in the Filter implementation (caused by a different behaviour of the new NHibernate).

Updated the HttpModuleCheckValidUser to consider the user online and update the activity date.

24 Mar 2007 - Version 0.9

Note: This version has some changes on the database schema. You can upgrade an old database using the SQL scripts inside the SQLScript folder (SQLScript\UpgradeY.YtoX.X).

Fixed a bug in the TransactionScope to correctly execute the rollback when the object is Disposed (I think that this bug occurs only on MySQL).

Fixed a bug to correctly show the update date of the archived articles. Removed the OriginalDate column from the WikiVersionedArticle table and changed the code that creates a VersioneArticle instance to copy the UpdateDate and InsertDate column from the source Article table.

Better exception if an article name is already used.

Improved demo website (see ChangeLog.txt).

14 Feb 2007 - Version 0.8.6.0

Fixed an error that prevents inserting a null or empty description when generating the RSS item.

Now, the Membership and Role providers implementation use a case insensitive search for user name and e-mail (like the MS provider).

28 Jan 2007 - Version 0.8.5.0

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

License

This article, along with any associated source code and files, is licensed under The MIT License