Eucalypto - 使用 NHibernate 的 ASP.NET CMS 库

• 下载源代码和二进制文件 (Eucalypto_1_3) - 2.73 MB
• 下载演示网站源代码 (Eucalypto.Demo_1_3) - 2.65 MB

引言

Eucalypto 是一个开源 .NET 业务/服务器库，用于帮助编写 ASP.NET 内容管理网站。Eucalypto 目前支持以下功能：

• 用户/会员资格
• 角色
• 配置文件
• 论坛
  • 分类
  • 附件
  • 回复通知
  • 格式化文本
  • RSS
  • 类别级别权限
• 内容管理
  • 分类
  • 格式化文本
  • 附件
  • RSS
  • 类别级别权限
• 新闻
  • 分类
  • RSS
  • 类别级别权限

Eucalypto 使用 NHibernate 进行所有数据访问，并且可以与 NHibernate 支持的任何数据库（SQLite、SQL Server、MySQL、Firebird、Access、Oracle 等）一起使用。

Eucalypto 与 ASP.NET 2.0 良好集成，使用标准提供程序模型类（MembershipProvider、RoleProvider、ProfileProvider 等）。

为什么选择 Eucalypto？

我的目标是创建一个轻量级项目，可以在任何 ASP.NET 兼容环境中运行，而不需要特定的数据库或额外的框架。Eucalypto 由一组 .NET 程序集组成，您只需在项目中引用它们。

与许多其他类似项目不同，Eucalypto 没有预定义的用户界面。Eucalypto 只是一个可以从您的页面中使用的库。

Eucalypto 并非一劳永逸的解决方案。您只能使用 Eucalypto 功能的一个子集。例如，您可以使用 Eucalypto 的论坛，但继续使用现有解决方案管理用户和角色。每个功能都是独立的。因此，将 Eucalypto 集成到现有 ASP.NET 网站中非常容易。

如果以正确的方式配置和使用，我认为 Eucalypto 适用于许多情况，特别是因为它易于扩展（如果需要）。您始终可以实现自定义提供程序，或根据您的特殊需求更改默认实现。

Eucalypto 使用 NHibernate 进行所有数据访问；因此，您可以使用多种数据库服务器。有关支持的数据库列表，请参阅 NHibernate 文档。

有很多项目可以用来创建 CMS 门户，免费或商业的，具有与 Eucalypto 类似的功能；Eucalypto 的优点是什么？

• 您可以将 Eucalypto 与现有网站或架构（Web 部件、SharePoint、现有 CMS 门户等）集成
• 您可以支持高级或自定义用户界面（可访问性、全球化、WAP、XAML/WPF、AJAX 等）或使用不同的表示层，但使用相同的业务层
• 您可以轻松扩展/更改业务层（得益于提供程序架构）
• 您不受门户功能的限制
• 您可以使用多种数据库类型（得益于 NHibernate）
• 表示层和业务层之间有清晰的分离
• 您可以充分利用 ASP.NET 的强大功能，并使用众所周知的技术（母版页、主题、用户控件、会员资格等）

Eucalypto 的适用场景

Eucalypto 默认使用 SQLite 数据库，但借助 NHibernate，您可以配置 Eucalypto 使用许多其他数据库（SQL Server、MySQL、Oracle 等）。SQLite 数据库是小型网站的完美解决方案。如果您有数千名用户和访问量，可能最好使用另一种架构。

Eucalypto 必须由开发人员使用，不适用于最终用户或高级用户。您必须知道如何开发 ASP.NET 应用程序。

Eucalypto 有一些重要的优点，但也有一些缺点。最重要的考虑是使用 Eucalypto 创建网站需要一些开发和配置。Eucalypto 不是一个完整的门户网站，它是一个库。您需要一些时间来创建一个完整且运行的网站。

如果您正在寻找一个完整的门户或不同的解决方案，您可能会尝试以下其他项目：

• Microsoft Office SharePoint Server (MOSS)
• Joomla!
• Atlassian
• Rainbow project
• DotNetNuke®
• Community Server
• PHP-Nuke
• YetAnotherForum.NET
• My Web Pages Starter Kit
• 还有很多其他...

要求

目前，Eucalypto 使用 .NET 2.0、Windows、IIS 和 SQLite（或 SQL Server）开发。Eucalypto 使用 100% 托管代码编写，但有些引用未编译为托管库（例如 SQLite）。

可能，使用正确的数据库（如 MySQL），Eucalypto 也可以在 Linux 和 Mono 上运行，但我目前还没有测试。我不知道 NHibernate 和 Log4net 的最新版本是否与其他平台完全兼容，但我希望将来不会有太多问题。

软件包

Eucalypto 由两个软件包组成：

• Eucalypto1 - Eucalypto 主软件包。包含 Eucalypto 的源代码和二进制文件。
  • Eucalypto - Eucalypto.dll 程序集
  • Eucalypto.Test - Eucalypto NUnit 测试程序集
• Eucalypto1.Demo - 演示软件包
  • WebSite - ASP.NET 网站演示

演示网站

如果您想查看代码或修改它，您也可以将演示项目安装到您的服务器上。以下是在您的服务器上运行 Eucalypto 演示项目的步骤：

• 下载 Eucalypto.Demo 软件包，用 Visual Studio 2005 打开它，并运行 WebSite 项目
• 打开 Setup.aspx 页面以配置数据库并创建管理员用户
• 打开 Admin/Default.aspx 处的管理页面以执行管理任务

现在，您可以开始使用 Eucalypto 演示项目。如果您需要更多关于可用配置的信息，请参阅以下部分。

创建您的网站

开始使用 Eucalypto 的一种常见方法是下载 Eucalypto.Demo 软件包并将其用作起点。Eucalypto.Demo 包含一些有用的类和工作配置。以下是 Eucalypto.Demo 组件的简要说明：

• \web.config - 主配置文件。
• \Site.master - 用于母版页的页面。
• \Global.asax - 主应用程序类。
• \Controls\*.* - 一些常见的用户控件。
• \Admin\*.* - 管理页面。
• \App_Themes\*.* - 主题、皮肤、CSS 和图片。
• \Setup.aspx - 用于创建数据库架构的页面（可在生产环境中删除）。
• \User\*.* - 用户管理页面（用户设置、更改密码等）。
• \Forum\*.* - 论坛管理页面。
• \Wiki\*.* - Wiki/文章管理页面。
• \News\*.* - 新闻管理页面。

许多页面都可以简单地用作起点，如果您已经熟悉 ASP.NET，您会发现使用的代码非常简单。

有关配置文件的更多信息，请参阅配置部分。有关所需引用的更多信息，请参阅引用部分。

提供程序概述

Eucalypto 的所有基本功能都是使用提供程序模型模式（类似于控制反转的模式）创建的。提供程序模型模式保证了易于定制和扩展。如果您愿意，您可以创建自己的提供程序，将数据保存到另一个数据源，或使用不同的格式，或使用特殊的业务规则。

ASP.NET 2.0 已经将提供程序模式用于会员资格、角色和配置文件功能。

目前，Eucalypto 实现了这些提供程序：

• Eucalypto.Membership.EucalyptoMembershipProvider - System.Web.Security.MembershipProvider 的实现。
• Eucalypto.Roles.EucalyptoRoleProvider - System.Web.Security.RoleProvider 的实现。
• Eucalypto.Notification.EucalyptoSmtpNotificationProvider - 一个新的提供程序，可用于使用 SMTP 和预配置的电子邮件模板向用户发送通知。由论坛提供程序用于通知用户。
• Eucalypto.Profile.EucalyptoProfileProvider - System.Web.Profile.ProfileProvider 的实现。
• Eucalypto.Forum.EucalyptoForumProvider - 一个新的提供程序，可用于创建完整的论坛解决方案。
• Eucalypto.Wiki.EucalyptoWikiProvider - 一个新的提供程序，可用于插入、更新和检索文章。
• Eucalypto.News.EucalyptoNewsProvider - 一个新的提供程序，可用于管理新闻。

每个提供程序都是相互独立的。例如，您可以将论坛提供程序与 Eucalypto 数据库一起使用，并将会员提供程序与默认的 SQL Server 数据库一起使用。

配置

根据您要使用 Eucalypto 的哪一部分，您需要不同的设置。通常，最重要的设置是连接字符串。

您可以在 web.config 中创建一个标准的 connectiostring 元素，并设置一个具有以下格式的连接字符串：

DriverClass=DRIVER;Dialect=DIALECT;CONNECTION_STRING

连接字符串由三个部分组成：

• DriverClass=DRIVER - 要使用的 NHibernate 驱动程序。有关驱动程序的更多详细信息，请参阅 NHibernate 文档。
• Dialect=DIALECT - 要使用的 NHibernate 方言。有关方言的更多详细信息，请参阅 NHibernate 文档。
• CONNECTION_STRING - 连接字符串的其他部分直接使用，并且对于每个驱动程序可能不同。

前两个属性用于 NHibernate 配置。您还可以使用一个特殊变量 |DataDirectory|，它将被替换为站点服务器应用程序数据路径。

SQLite

在以下代码中，您可以看到连接到 SQLite 数据库的示例：

<connectionStrings>
    <clear/>
    <!-- SQLite connection string -->
    <add name="DefaultConnection"
          connectionString="DriverClass=NHibernate.Driver.SQLite20Driver;
                            Dialect=NHibernate.Dialect.SQLiteDialect;
                            Data Source=|DataDirectory|\data.db3" />
</connectionStrings>

请记住，您必须使用 ASP.NET 进程具有读写权限的目录。以下是在 Windows 2003 上配置 App_Data 文件夹写权限的示例：

如果 SQLite 驱动程序不存在，它会自动创建数据库文件。

SQL Server

在以下代码中，您可以看到 SQL Server 2005 的连接字符串：

<connectionStrings>
    <!-- SQL Server 2005 connection string -->
    <add name="DefaultConnection"
         connectionString="DriverClass=NHibernate.Driver.SqlClientDriver;
                 Dialect=NHibernate.Dialect.MsSql2005Dialect;
                 Data Source=localhost;
                 Initial Catalog=Eucalypto;Integrated Security=SSPI;"
                            />
</connectionStrings>

您必须手动创建空数据库，然后使用“SQL Server Management Studio”或适当的 SQL 脚本向 ASP.NET 进程授予数据库的读写权限。有关安全性的更多信息，请尝试查看以下 MSDN 文章：'How To: Connect to SQL Server Using Windows Authentication in ASP.NET 2.0'。

要创建数据库，您可以使用此脚本：

CREATE DATABASE Eucalypto

其他数据库

以下是针对最常见数据库的连接字符串列表：

• SQLite - DriverClass=NHibernate.Driver.SQLite20Driver; Dialect=NHibernate.Dialect.SQLiteDialect; Data Source=|DataDirectory|\data.db3
• SQL Server 2005 - DriverClass=NHibernate.Driver.SqlClientDriver; Dialect=NHibernate.Dialect.MsSql2005Dialect; Data Source=localhost;Initial Catalog=Eucalypto;Integrated Security=SSPI;
• SQL Server Express 2005 - DriverClass=NHibernate.Driver.SqlClientDriver; Dialect=NHibernate.Dialect.MsSql2005Dialect;data source=.\SQLEXPRESS;Integrated Security=SSPI;AttachDBFilename =|DataDirectory|data.mdf;User Instance=true
• SQL Server 2000 - DriverClass=NHibernate.Driver.SqlClientDriver; Dialect=NHibernate.Dialect.MsSql2000Dialect;Data Source=localhost;Initial Catalog=Eucalypto;Integrated Security=SSPI;
• MySQL - DriverClass=NHibernate.Driver.MySqlDataDriver; Dialect=NHibernate.Dialect.MySQLDialect; Database=Eucalypto;Data Source=SomeServer;User Id=SomeUser;Password=SomePassword
• ...

创建数据库架构

现在，您必须创建 Eucalypto 数据库架构。我编写了一个页面 Setup.aspx（在 WebSiteTest 项目中），可用于创建所需的数据库架构。您通常可以将此页面复制到您的项目中并用浏览器打开它（注意：出于安全原因，此页面只能从本地服务器机器执行）。

此页面使用 Eucalypto.SchemaGenerator.GenericGenerator 类为所选连接字符串生成架构。您可以使用页面顶部的下拉列表选择连接字符串（此下拉列表加载了 web.config 中配置的当前连接），然后单击“创建架构”按钮生成架构。

Eucalypto.SchemaGenerator.GenericGenerator 类使用 NHibernate.Tool.hbm2ddl.SchemaExport 代码生成架构。如果遇到问题，您始终可以手动创建数据库表。

请记住，目前此工具无法升级现有表。如果表已存在，其内容将被删除。

在 Setup.aspx 页面中，还有一个创建管理员用户和角色的功能；您只需选择一个新密码并单击“创建管理员用户”按钮即可。

管理员功能

我为最重要的管理任务创建了一组页面。您可以将 WebSiteTest 项目的 Admin 文件夹复制到您的网站中。在此文件夹中，您可以找到一些页面来配置 Eucalypto 的许多功能。

打开 Admin/Default.aspx 页面以获取可用配置的概述。此页面要求您以管理员身份登录（administrators 角色），因此您必须首先正确配置用户和角色并创建管理员用户。

配置完主要功能后，您可以开始使用 Eucalypto。有关每个功能的配置，请参阅以下部分。

会员资格和角色

会员资格提供程序是一个 ASP.NET 提供程序。ASP.NET 会员资格为您提供了一种内置方式来验证和存储用户凭据，它可以与 ASP.NET 角色管理集成，为您的网站提供授权服务。

配置

要使用会员资格和角色功能，您必须配置 ASP.NET 以使用 Eucalypto 提供程序，将此部分添加到 web.config 文件中：

<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <system.web>

    <!-- Authentication mode -->
    <authentication mode="Forms">
      <forms loginUrl="Login.aspx" defaultUrl="Default.aspx">
      </forms>
    </authentication>
    
    <!-- Authorization-->
    <authorization>
      <!-- Allow all -->
      <allow users="?"/>
    </authorization>
    
    <!-- Membership Provider -->
    <membership defaultProvider="EucalyptoMembershipProvider">
      <providers>
        <clear/>
        <add name="EucalyptoMembershipProvider" 
             type="Eucalypto.Membership.EucalyptoMembershipProvider, Eucalypto"
             connectionStringName="DefaultConnection"
             applicationName="Default"
             minRequiredNonAlphanumericCharacters="0"
             minRequiredPasswordLength="4"
              />
      </providers>
    </membership>
    
    <!-- Role Provider -->
    <roleManager enabled="true" defaultProvider="EucalyptoRoleProvider">
      <providers>
        <clear />
        <add name="EucalyptoRoleProvider" 
             connectionStringName="DefaultConnection" 
             applicationName="Default"
             type="Eucalypto.Roles.EucalyptoRoleProvider, Eucalypto" />
      </providers>
    </roleManager>
  </system.web>
</configuration>

您可以使用标准 ASP.NET 配置网站配置用户和角色

用法

有很多关于 ASP.NET 会员资格和角色功能的好文章；以下是一些链接：

• MSDN - 会员资格简介
• MSDN - 解释：ASP.NET 2.0 中的窗体身份验证
• 4guysfromrolla.com - 检查 ASP.NET 2.0 的会员资格、角色和配置文件，作者 Scott Mitchell
• OdeToCode.com - ASP.NET 2.0 中的会员资格和角色提供程序，作者 Scott Allen

请注意，目前，EucalyptoMembershipProvider 仅支持哈希密码，不支持密码检索功能（EnablePasswordRetrieval），仅支持密码重置。

配置文件

配置文件提供程序是一个 ASP.NET 提供程序。您可以通过定义和使用配置文件属性为网站用户提供自定义体验。您可以使用配置文件属性来跟踪应用程序所需的任何自定义信息。

配置

要使用配置文件功能，您必须配置 ASP.NET 以使用 Eucalypto 提供程序，将此部分添加到 web.config 文件中：

<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <system.web>

    <!-- Profile -->
    <!-- Enable anonymousIdentification only if really required -->
    <anonymousIdentification enabled="true" />
    <profile defaultProvider="EucalyptoProfileProvider">
      <providers>
        <clear />
        <add name="EucalyptoProfileProvider" 
            type="Eucalypto.Profile.EucalyptoProfileProvider, Eucalypto"
            connectionStringName="DefaultDB" applicationName="Default" />
      </providers>
      <properties>
        <!-- Just for test -->        
        <add name="FavoriteColor" type="String" 
             defaultValue="Blue" allowAnonymous="true" />
      </properties>
    </profile>

  </system.web>
</configuration>

用法

有很多关于 ASP.NET 配置文件功能的好文章；以下是一些链接：

• MSDN - ASP.NET 配置文件
• codeguru.com - ASP.NET 2.0 配置文件：您的 Web 应用程序的简单用户个性化，作者 Thiru Thangarathinam
• OdeToCode.com - ASP.NET 2.0 中的配置文件，作者 Scott Allen

通知

配置

要使用通知功能，您必须首先配置通知提供程序，将这些部分添加到 web.config 中：

<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <!-- Add the notification provider section -->
    <section name="notificationManager" 
       type="Eucalypto.Notification.NotificationProviderConfiguration, Eucalypto"/>
  </configSections>

  <!-- EMail SMTP configuration -->
  <system.net>
    <mailSettings>
      <smtp>
        <network host="yourSmtpServer" port="25" 
                 userName="username" password="password" />
      </smtp>
    </mailSettings>
  </system.net> 

  <!-- Notification provider -->
  <notificationManager>
    <providers>
      <add name="EucalyptoForumSmtp" 
           type="Eucalypto.Notification.EucalyptoSmtpNotificationProvider, Eucalypto"
           template="App_Data\MailTemplate_Forum.xml" />
    </providers>
  </notificationManager>

</configuration>

使用 enabled 属性启用或禁用提供程序。template 属性必须配置一个有效的 XML 文件，其中包含发送电子邮件时使用的模板数据。以下是一个示例：

<?xml version="1.0" encoding="utf-8" ?>
<template>
  <sender>youremail@yourserver.com</sender>
  <subject>[Eucalypto - Forum ?forumDescription?] ?title?</subject>
  <body html="true">
    <![CDATA[
    <p>Forum: <strong>?forumDescription?</strong></p>
    <p>You have received a response from ?user?.</p>
    
    <p>Title: <strong>?title?</strong></p>
    <p><i>?body?</i></p>
    <a href="http://yourserver/Forum/ViewTopic.aspx?id=?idtopic?">View topic</a>
    ]]>    
  </body>
</template>

您可以使用通知提供程序的用户指定的某些参数（例如，?title?，?user?，...），这些参数将被通知的实际数据替换。在这种情况下，我使用了论坛提供程序使用的参数。

用法

EucalyptoSmtpNotificationProvider 提供程序可以使用 SMTP（电子邮件）发送通知。您可以使用静态属性 Eucalypto.Notification.NotificationManager.Providers 读取已配置提供程序的列表。

以下是一个发送通知的简单示例：

//Create the parameters list

Dictionary<string, string> parameters = new Dictionary<string, string>();
parameters.Add("?title?", message.Title);
parameters.Add("?body?", xhtml);
parameters.Add("?user?", message.Owner);

System.Web.Security.MembershipUser destinationUser = 
       System.Web.Security.Membership.GetUser(user);
if (destinationUser != null &&
    NotificationProvider.UserCanReceiveNotification(destinationUser))
{
    //Send a notification

    NotificationProvider.NotifyUser(destinationUser, parameters);
}

论坛

配置

要使用论坛功能，您必须首先配置论坛提供程序，将这些部分添加到 web.config 中：

<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <!-- Add the forum provider section -->
    <section name="forumManager" 
        type="Eucalypto.Forum.ForumProviderConfiguration, Eucalypto"/>
  </configSections>
  
  <!-- Forum provider -->
  <forumManager defaultProvider="EucalyptoForumProvider">
    <providers>
      <clear/>
      <add name="EucalyptoForumProvider" 
           type="Eucalypto.Forum.EucalyptoForumProvider, Eucalypto"
           connectionStringName="DefaultConnection"  
           notificationProvider="EucalyptoSmtp" />
    </providers>
  </forumManager>
</configuration>

您可以使用这些属性配置论坛提供程序：

• connectionStringName - 用于存储论坛数据的连接。
• notificationProvider - 用于通知用户有人回复消息的通知提供程序。有关更多详细信息，请参阅通知部分。留空表示不使用通知提供程序。

默认提供程序是 EucalyptoForumProvider，它使用 NHibernate 存储任何与论坛相关的数据。请注意，如果需要，您始终可以实现自定义论坛提供程序。

在内部，论坛提供程序使用通知提供程序，因此通常您也必须配置它。

用法

您可以在 Eucalypto.Forum 命名空间中找到所有与论坛相关的类。您必须使用 Eucalypto.Forum.ForumManager 类来插入、读取或删除论坛数据。主要实体是：

• Category - 论坛类别表示一个论坛。论坛类别由主题列表组成。
• Topic - 主题表示讨论的主题，是最初发布到讨论的消息。主题由消息列表组成。
• Message - 消息是论坛的主要实体。表示论坛用户发布的文本。

您可以启用或禁用附件、接受的扩展名和最大文件大小，或配置每个论坛的安全性。使用管理部分配置每个论坛。

论坛消息以 XHTML 格式保存。

以下是如何创建论坛类别、插入一些消息并搜索它们的示例：

//Create category

Eucalypto.Forum.Category category = 
  Eucalypto.Forum.ForumManager.CreateCategory("test", "test");

//Create a topic (with a message)

Eucalypto.Forum.Topic topic;
Eucalypto.Forum.Message message;
Eucalypto.Forum.ForumManager.CreateTopic(category, "user1", 
  "Title 1", "<p>Body text</p>", 
  null, out topic, out message);

//Create an answer (message)

Eucalypto.Forum.Message message1 = 
  Eucalypto.Forum.ForumManager.CreateMessage(topic, message.Id, 
  user1", "RE: Title 1", "<p>Response</p>", null);

//Create a second answer (message)

Eucalypto.Forum.Message message2 = 
  Eucalypto.Forum.ForumManager.CreateMessage(topic, message1.Id,
  "user1", "RE: Title 1", "<p>Response</p>", null);

//Create a second topic

Eucalypto.Forum.Topic topic2;
Eucalypto.Forum.Message message3;
Eucalypto.Forum.ForumManager.CreateTopic(category, "user2", 
          "Title 2", "<p>Body text</p>",
          null, out topic2, out message3);

//Find the previous messages (filtering the owner field)

Eucalypto.PagingInfo paging = new Eucalypto.PagingInfo(10, 0);
Eucalypto.Forum.ForumManager.FindMessages(Eucalypto.Filter.MatchOne( category.Name),
                                            null, 
                                            Eucalypto.Filter.MatchOne("user1"),
                                            null,
                                            null, null, 
                                            paging);

//Find the previous messages (filtering by a field)

Eucalypto.Forum.ForumManager.FindMessages(Eucalypto.Filter.MatchOne(category.Name), 
                                            Eucalypto.Filter.ContainsOne("RE:"),
                                            null, null, null, null, paging);

//Delete a topic

Eucalypto.Forum.ForumManager.DeleteTopic(topic);

//Create another topic

Eucalypto.Forum.Topic topic3;
Eucalypto.Forum.Message message4;
Eucalypto.Forum.ForumManager.CreateTopic(category, "test", "Title 3", 
          "<p>Body text</p>", null, out topic3, out message4);

//Delete the category

Eucalypto.Forum.ForumManager.DeleteCategory(category);

内容管理（Wiki 文章提供程序）

配置

要使用内容管理功能，您必须首先配置 Wiki 提供程序，将这些部分添加到 web.config 中：

<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <!-- Add the wiki provider section -->
    <section name="wikiManager" 
             type="Eucalypto.Wiki.WikiProviderConfiguration, Eucalypto"/>
  </configSections>
  
  <!-- Wiki provider -->
  <wikiManager defaultProvider="EucalyptoWikiProvider">
    <providers>
      <clear/>
      <add name="EucalyptoWikiProvider" 
           type="Eucalypto.Wiki.EucalyptoWikiProvider, Eucalypto"
           connectionStringName="DefaultDB" />
    </providers>
  </wikiManager>
</configuration>

您可以使用这些属性配置 Wiki 提供程序：

• connectionStringName - 用于存储文章数据的连接。

默认提供程序是 EucalyptoWikiProvider，它使用 NHibernate 存储任何与文章相关的数据。请注意，如果需要，您始终可以实现自定义提供程序。

用法

您可以在 Eucalypto.Wiki 命名空间中找到所有与 Wiki 相关的类。您必须使用 Eucalypto.Wiki.WikiManager 类来插入、读取或删除文章数据。主要实体是：

• Category - Wiki 类别。类别由文章列表组成。
• Article - 文章表示内容。文章可以包含 FileAttachment 列表和 VersionedArticle 列表。
• FileAttachment - 消息是论坛的主要实体。表示论坛用户发布的文本。
• VersionedArticle - 每次用户更新 Article 时，以前的版本都会保存到新的 VersionedArticle 实例中。

您可以启用或禁用附件、接受的扩展名和最大文件大小，或配置每个类别的安全性。使用管理部分配置每个类别。

文章内容以 XHTML 格式保存。

以下是插入一些文章的示例：

//Create a category

Eucalypto.Wiki.Category category = 
  Eucalypto.Wiki.WikiManager.CreateCategory("test", "test");

//Create an article

Eucalypto.Wiki.Article article = 
  Eucalypto.Wiki.WikiManager.CreateArticle(category, "owner1",
                             "article1", "Title 1", "Description", 
                             "<p>body 1</p>");

//Create a second article

Eucalypto.Wiki.Article article2 = 
  Eucalypto.Wiki.WikiManager.CreateArticle(category, "owner2",
                             "article2", "Title 2", "Description", 
                             "<p>bla bla bla search1 bla bla bla</p>");

//Update an article

article.Body = "<p>body 1 v2</p>";
string myTag = Guid.NewGuid().ToString();
article.Tag = myTag;
Eucalypto.Wiki.WikiManager.UpdateArticle(article, true);

//Read the first version of the article

Eucalypto.Wiki.ArticleBase articleV1 = 
          Eucalypto.Wiki.WikiManager.GetArticleByVersion(article, 1);

//Find an article (filtering using the search string)

Eucalypto.PagingInfo paging = new Eucalypto.PagingInfo(10, 0);
IList<Eucalypto.Wiki.Article> articles = 
   Eucalypto.Wiki.WikiManager.FindArticles(Eucalypto.Filter.MatchOne(category.Name),
                                    Eucalypto.Filter.ContainsAll("search1"), 
                                    null, null, null, null, null, 
                                    Eucalypto.Wiki.ArticleStatus.All,
                                    paging);

//Find another article (filtering using the Tag)

articles = Eucalypto.Wiki.WikiManager.FindArticles(null, null, null, null,
                                    Eucalypto.Filter.MatchOne(myTag), null, null, 
                                    Eucalypto.Wiki.ArticleStatus.All, paging);

//Delete an article

Eucalypto.Wiki.WikiManager.DeleteArticle( article );

//Delete the category

Eucalypto.Wiki.WikiManager.DeleteCategory( category );

新闻

配置

要使用新闻功能，您必须首先配置新闻提供程序，将这些部分添加到 web.config 中：

<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <!-- Add the news provider section -->
    <section name="newsManager" 
             type="Eucalypto.News.NewsProviderConfiguration, Eucalypto"/>
  </configSections>
  
  <!-- News provider -->
  <newsManager defaultProvider="EucalyptoNewsProvider">
    <providers>
      <clear/>
      <add name="EucalyptoNewsProvider" 
           type="Eucalypto.News.EucalyptoNewsProvider, Eucalypto"
           connectionStringName="DefaultDB" />
    </providers>
  </newsManager>
    
</configuration>

您可以使用这些属性配置新闻提供程序：

• connectionStringName - 用于存储新闻数据的连接。

默认提供程序是 EucalyptoNewsProvider，它使用 NHibernate 存储任何与新闻相关的数据。请注意，如果需要，您始终可以实现自定义新闻提供程序。

用法

您可以在 Eucalypto.News 命名空间中找到所有与新闻相关的类。您必须使用 Eucalypto.News.NewsManager 类来插入、读取或删除新闻数据。主要实体是：

• Category - 新闻类别由项目列表组成。
• Item - 项目表示一条新闻行。项目由标题、URL、描述等组成。

使用管理部分配置每个新闻类别。

以下是如何创建新闻类别并插入一些项目的示例：

//Create a category

Eucalypto.News.Category category = 
  Eucalypto.News.NewsManager.CreateCategory("test", "test");

//Create an item

Eucalypto.News.Item item = Eucalypto.News.NewsManager.CreateItem(category, 
                           "owner1", "Title 1", 
                           "Description 1", 
                           "http://www.google.com/", 
                           "DevAge home page", new DateTime(2006, 1, 3));
//Create a second item

Eucalypto.News.Item item2 = Eucalypto.News.NewsManager.CreateItem(category, 
                            "owner1", "Title 2", 
                            "Description 2", 
                            "http://www.google.com/", "DevAge home page", 
                            new DateTime(2006, 10, 3));

//Update an item

item.Description = "Description modified";
Eucalypto.News.NewsManager.UpdateItem(item);

//Find the previous items

Eucalypto.PagingInfo paging = new Eucalypto.PagingInfo(10, 0);
Eucalypto.News.NewsManager.FindItems(Eucalypto.Filter.MatchOne(category.Name),
                                    null, null, null,
                                    paging);

//Delete an item

Eucalypto.News.NewsManager.DeleteItem(item2);

//Delete the entire category

Eucalypto.News.NewsManager.DeleteCategory(category);

自定义实体

您可以使用自定义实体扩展 Eucalypto，以存储应用程序的额外信息。Eucalypto 公开了一系列类来简化自定义实体的创建和集成。在以下部分中，您将看到如何创建一个自定义 Dog 实体，包括数据访问类。

请记住，Eucalypto 使用 NHibernate 进行所有数据访问，所以我通常建议您首先阅读并理解 NHibernate 架构和代码。Eucalypto 只是隐藏了一些配置和代码，但对 NHibernate 有一定的经验是很重要的。

第一步是配置 Eucalypto 以识别和使用您的程序集。您可以通过在配置文件中添加一个自定义部分来配置 Eucalypto：

<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <!-- Add eucalypto section -->
    <section name="eucalypto" 
             type="Eucalypto.Configuration.EucalyptoSection, Eucalypto" />
  </configSections>

  <!-- Specific Eucalypto configuration -->
  <eucalypto>
    <!-- List of assembly to use for the mappings -->
    <mappings>
      <add assembly="MyAssembly" />
    </mappings>
  </eucalypto>

</configuration>

上述配置中的程序集 MyAssembly 是将包含您的实体的自定义程序集。

现在，您可以创建实际的实体类。

namespace Eucalypto.Test.CustomEntity
{
    public class Dog
    {
        protected Dog(){ }

        public Dog(string name, string displayName)
        {
            Name = name;
            DisplayName = displayName;
        }

        private string mId;
        public virtual string Id
        {
            get { return mId; }
            protected set { mId = value; }
        }

        private string mName;
        public virtual string Name
        {
            get { return mName; }
            protected set { mName = value; }
        }

        private string mDisplayName;
        public virtual string DisplayName
        {
            get { return mDisplayName; }
            set { mDisplayName = value; }
        }

        private string mDescription;
        public virtual string Description
        {
            get { return mDescription; }
            set { mDescription = value; }
        }
    }
}

如您所见，这只是一个标准的 .NET 类，唯一需要的代码是用于实体主键的 Id 属性和一个默认构造函数（public 或 protected）。在您的程序集中编译此类的。现在，您可以创建使用 NHibernate 配置文件定义数据库映射的文件：

<?xml version="1.0" encoding="utf-8" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.2">
  <class name="Eucalypto.Test.CustomEntity.Dog, MyAssembly" table="Dog">
    <id name="Id" column="Id" type="String" length="32" >
      <generator class="uuid.hex">
        <param name="format">N</param>
      </generator>
    </id>
    <property name="Name" type="String">
      <column name="Name" unique-key="KeyName" not-null="true" length="100"/>
    </property>
    <property name="DisplayName" column="DisplayName" 
              type="String" length="100" not-null="true" />
    <property name="Description" column="Description" type="String" length="300" />
  </class>
</hibernate-mapping>

您必须将此 XML 保存为程序集的嵌入资源，扩展名为 .hbm.xml（例如，Dog.hbm.xml；NHibernate 需要 .hbm.xml）。您通常可以使用 NHibernate 的任何功能（嵌套类、集合、继承等）；有关更多详细信息，请参阅 NHibernate 文档。

下一步是创建数据访问类。请注意，您也可以使用自定义数据访问类，但使用 Eucalypto 代码可以节省您一些时间：

namespace Eucalypto.Test.CustomEntity
{
    public class DogDataStore : EntityDataStoreBase<Dog, string>
    {
        public DogDataStore(TransactionScope transactionScope)
            : base(transactionScope)
        {
        }
        public Dog FindByName(string name)
        {
            ICriteria criteria = CreateCriteria();
            criteria.Add(Expression.Eq("Name", name));

            return FindUnique(criteria);
        }
        public IList<Dog> FinAll()
        {
            ICriteria criteria = CreateCriteria();
            criteria.AddOrder(Order.Asc("DisplayName"));

            return base.Find(criteria);
        }
    }
}

EntityDataStoreBase 是一个通用的抽象类，可用于基本数据访问功能（插入、删除、更新等）。您只需实现您的特定功能，通常是自定义选择和过滤。

就是这样。现在，您可以使用您的实体了。以下是您如何使用自定义实体的示例：

ConnectionParameters parameters = ConnectionParameters.Create("DefaultDB");

using (TransactionScope transaction = new TransactionScope(parameters))
{
    CustomEntity.DogDataStore dataStore = 
      new Eucalypto.Test.CustomEntity.DogDataStore(transaction);

    //Insert 3 dogs

    dataStore.Insert(new Eucalypto.Test.CustomEntity.Dog("black", "Black"));
    dataStore.Insert(new Eucalypto.Test.CustomEntity.Dog("white", "White"));
    dataStore.Insert(new Eucalypto.Test.CustomEntity.Dog("red", "Red"));

    //Delete a dog

    CustomEntity.Dog redDog = dataStore.FindByName("red");
    dataStore.Delete(redDog.Id);

    //Update a dog

    CustomEntity.Dog blackDog = dataStore.FindByName("black");
    blackDog.DisplayName = "Black dog";

    //Commit all the changes

    transaction.Commit();
}

请注意，您需要一个有效的连接字符串（在示例中称为 DefaultDB）和一个有效的数据库。有关更多信息，请参阅上一节的配置。如果您愿意，您还可以使用自动架构生成器生成自定义实体的架构；在这种情况下，您需要另一个步骤来这样配置架构生成器：

[assembly: Eucalypto.SchemaGenerator.SetupMapping("Custom", 
          "Eucalypto.Test.CustomEntity.Dog, MyAssembly")]

然后，您可以使用此代码自动生成数据库的架构：

Eucalypto.ConnectionParameters config = 
   ConnectionParameters.Create(Settings.CONNECTIONSTRING);

Eucalypto.SchemaGenerator.GenericGenerator generator =
        new Eucalypto.SchemaGenerator.GenericGenerator(config);

foreach (string cat in generator.GetSchemaCategories())
{
    generator.CreateSchemaTable(cat);
}

上述代码为所有可用类别（也包括系统 Eucalypto 类别）创建架构。每个类别都在 SetupMappingAttribute 的第一个参数中定义。

实现细节

NHibernate

“NHibernate 是 Hibernate Core for Java 到 .NET Framework 的移植。它处理将普通 .NET 对象持久化到基础关系数据库中以及从中持久化。”

• NHibernate 网站

您可以配置 NHibernate 使用多种数据库：SQL Server、Oracle、MySQL 等。Eucalypto 的默认数据库是 SQLite。

SQLite

“SQLite 是一个小的 C 库，它实现了一个独立的、可嵌入的、零配置的 SQL 数据库引擎。”

• SQLite 项目的 .NET 修改版本。我使用了这个版本，特别感谢 Robert Simpson 的工作。
• 原始 SQLite 项目.

要查询或更新 SQLite 数据库，我强烈建议使用 SQLite Spy，这是一个非常强大且有用的工具。感谢 Ralf Junker。您可以从这里下载它。

通常，您可以在 App_Data 目录中找到 SQLite 数据库。

重要注意事项：SQLite 目前是用 C++ 编写的非托管库。因此，您必须记住 SQLite 必须以完全信任权限执行。如果您想使用共享主机（在托管公司上运行您的网站），您必须考虑它们通常配置为中等信任。中等信任安全性会阻止任何 P/Invoke 代码，并且 SQLite 无法运行。在这种情况下，您可以要求您的托管公司以完全信任运行您的应用程序，或者要求在 GAC 中安装 SQLite 库。无论如何请记住，Eucalypto 可以与许多其他数据库一起使用。例如，许多托管公司提供 MySQL、Access 或 SQL Server。

Log4Net

“log4net 是一个帮助程序员将日志语句输出到各种输出目标的工具。log4net 是优秀的 log4j 框架到 .NET 运行时的移植。”

• Log4Net 官方网站

Eucalypto 内部使用 log4net 记录异常和警告。整个 log4net 配置可以在 web.config 文件中更改。在 global.asax 文件中，我使用以下代码配置 Eucalypto：log4net.Config.XmlConfigurator.Configure()。通常，您可以在 App_Data 目录中找到 log4net 日志文件。

CSS

我讨厌 CSS .... 每次我必须处理页面布局时，我都会和 CSS 斗争。因此，我总是寻找一些简单明了的例子。

我要感谢 Alessandro Fulciniti，他为 CSS 做出了巨大的贡献。对我来说，这些是最简洁易用的 CSS 布局。

对于这个网站，我使用了我在上述页面上找到的 CSS 布局的修改版本。

提供程序模型

有关 ASP.NET 提供程序模型的更多信息，我建议您阅读这些 MSDN 文章：

• “提供程序模型设计模式和规范”
• “ASP.NET 2.0 提供程序模型：提供程序模型简介”

RSS

Eucalypto 有一个集成的 RSS 库，由 Brian Kuhn 编写。感谢他的工作。

更多信息请访问 “RSS 2.0 类库和联合提供程序”。

有关 RSS 格式和规范的信息，您可以查看此网站。

XHTML

用户编写的所有内容都保存为 XHTML。例如，所有 Wiki 内容和论坛消息都使用 XHTML 编写。我选择这种格式的原因有很多：

• 它是网页的本地格式，并受许多平台/浏览器支持
• 它是一个标准且众所周知的格式
• 人类和代码（使用任何 XML 解析器）都可以轻松解析和修改
• 可以轻松转换为其他格式
• 可以轻松用于电子邮件

NUnit

“NUnit 是一个适用于所有 .NET 语言的单元测试框架。”

• NUnit 官方网站

我为 Eucalypto (Eucalypto.Test) 创建了一个测试项目，其中包含一些测试用例。有关 NUnit 配置，请参阅 Eucalytpo.nunit。

HttpModuleCheckValidUser

我创建了一个自定义 HttpModule Eucalypto.Membership.HttpModuleCheckValidUser 以添加额外的安全检查。基本上，此 HTTP 模块用于检查已通过身份验证的用户是否已批准且未锁定。这很有用，例如，当用户使用“记住我”cookie 自动进行身份验证时。

要使用此模块，您必须在 system.web 配置元素中添加此配置：

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

参考文献

以下是您需要引用的必需程序集：

• Eucalypto.dll - 主 Eucalypto 程序集
• NHibernate.dll - NHibernate 主程序集
• Castle.DynamicProxy.dll - NHibernate 使用的动态代理生成器
• Iesi.Collections.dll - NHibernate 使用的高级集合
• NHibernate.Tool.hbm2net.dll - NHibernate 的架构生成器
• log4net.dll - 用于日志记录
• [System.Data.SQLite.DLL] - 可选，仅在使用 SQLite 时需要
• [nunit.framework.dll] - 可选，仅适用于 Eucalypto.Test NUnit 项目

未来工作

• 扩展单元测试
• 压力/性能改进
• 为 Eucalypto 提供程序创建一组 Web 服务器控件（或带皮肤的控件），以便于重用
• 改进搜索支持
• 论坛和文章的 HTML 文本编辑器 (FCKeditor?)
• 问题跟踪系统
• 相册
• 博客

历史

2009 年 6 月 7 日 - 版本 1.3

• 更新了本文顶部的链接

2007 年 5 月 2 日 - 版本 1.2

• 修复了 Filter 类在使用 MatchMode.End 或 MatchMode.Start 时的一个错误。
• 修复了文档中的英文错误。

2007 年 4 月 20 日 - 版本 1.1

• 改进了配置类以获得更好的可扩展性。
• 改进了架构生成器，现在可以扩展自定义类和程序集。
• 将类 Eucalypto.Configuration 重命名为 Eucalypto.ConnectionParameters。
• 增加了使用配置文件中的 Eucalypto 配置部分添加自定义映射程序集的功能，并创建了一个可供自定义实体使用的通用设置配置。
• 添加了自定义实体示例和测试。
• 新增文档部分，展示如何创建和使用自定义实体。
• 修复了 TOC 生成器，使其不考虑标题标签内的空格字符。
• 改进了用于检查实体特定操作权限的安全代码 (SecurityHelper)。现在，支持使用前缀“!”拒绝角色的权限。

2007 年 4 月 4 日 - 版本 1.0

• 更新了 NHibernate 1.2.0.3001 和 SQLite 1.0.40.0 的引用。
• 添加了 Eucalypto/Membership/HttpModuleCheckValidUser.cs HttpModule，用于检查用户在使用 Cookie 进行身份验证后是否仍然有效。
• 修复了 Filter 实现中的一个错误（由新 NHibernate 的不同行为引起）。
• 更新了 HttpModuleCheckValidUser 以考虑用户在线并更新活动日期。

2007 年 3 月 24 日 - 版本 0.9

注意：此版本对数据库架构进行了一些更改。您可以使用 SQLScript 文件夹（SQLScript\UpgradeY.YtoX.X）中的 SQL 脚本升级旧数据库。

• 修复了 TransactionScope 中的一个错误，以在对象被释放时正确执行回滚（我认为此错误仅在 MySQL 上发生）。
• 修复了一个错误，可以正确显示已归档文章的更新日期。从 WikiVersionedArticle 表中删除了 OriginalDate 列，并更改了创建 VersioneArticle 实例的代码，以从源 Article 表复制 UpdateDate 和 InsertDate 列。
• 如果文章名称已被使用，则会抛出更好的异常。
• 改进了演示网站（请参阅 ChangeLog.txt）。

2007 年 2 月 14 日 - 版本 0.8.6.0

• 修复了生成 RSS 项目时阻止插入 null 或空描述的错误。
• 现在，会员和角色提供程序实现对用户名和电子邮件使用不区分大小写的搜索（与 MS 提供程序类似）。

2007 年 1 月 28 日 - 版本 0.8.5.0

• 首次公开发布。

许可证

Eucalypto 许可证 (MIT 风格)

版权所有 (c) 2007 Davide Icardi。

特此授予任何获得本软件及相关文档文件（“软件”）副本的人员免费处理本软件的权利，不受限制，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许接收本软件的人员这样做，但须遵守以下条件：

上述版权声明和本许可声明应包含在软件的所有副本或重要部分中。

本软件按“原样”提供，不提供任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和不侵权的担保。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同、侵权或其他诉讼中，因本软件或使用或处理本软件而引起或与之相关。