ASPPlayground.NET Version 3
Site Integration Package Readme

NOTE: Make sure you have forum version 3.0.1 installed and running properly before using this Site Integration Package (Membership Provider / Role Provider / Message Extractor Class).

ASPPlayground.NET V3 Site Integration Package provides the owner of the forum an easy way to interact with the data stored in the forum. Specifically this package allows you to use the following information:

1. Membership - through the membership provider model of ASP.NET 2.0, you can manage forum users in your own code with ease.
2. User Group - through the role provider model of ASP.NET 2.0, you can manage forum user group membership in your own code with ease.
3. Messages - using our simple message extractor, you can extract message list + actual messages using a few lines of code on your page.

Membership

The Membership Provider allows you to interact with our user database programmatically using the standard ASP.NET membership provider model. With our membership provider installed you can build your site using our forum database as the member data store. In other words, you can

1. Build a login page on your site and once a user is logged in, he is logged in to the forum as well - Single Sign On, and vice versa.
2. Build a registration page for your site and have users inserted into our database.
3. In addition, with our membership provider, you can
   1. Delete users from your site
   2. Allows Users to change / reset password
   3. Update Users' Email
   4. Approve users / Unlock (un-ban) users
   5. Build member list
   6. Look for users using email / login with wildcard character (%) support
   7. Get number of online users

User Group

Our forum software uses User Groups (Roles) extensively to manage permissions. The entire security model in the forum centers around the User Group system. In Version 3 of our forum, the user group system has been extended to include a lot more features than the previous version. Being able to manage User Group Membership in your own code gives you a lot of power on the forum system. Our User Group Management package is built according to the standard Role Provider Model of ASP.NET 2.0, which means you can use your current ASP.NET knowledge without having to lean additional stuff. With our Role Provider, you can

1. Easily add / delete users from a User Group (role)
2. Get a list of all available User Groups (roles)
3. List all users / Find specific user(s) who currently belong to a User Group (role)
4. List all User Group (role) a member currently belongs to
5. Whether a user is a member of a User Group (role)
6. List all available User Groups (roles)

Messages

It is often desirable to be able to show a few messages posted on the forum on your own site. Our Message Extractor class not only allows you to extract a list of threads / messages from a list of forums you specify, but also the actual messages (full content with HTML formatting) in a thread you pick. The class returns a generic List (Of ASPPGMessageItem), which can be bound to any ASP.NET List Controls (DropDownList, ListBox, CheckBoxList, BulletedList), Iterative Controls (Repeater, DataList), and View Controls (GridView, DataGrid, ListView).

ASPPGMessageItem has the following properties

• MessageLink string - the fully qualified link to the forum's message page (starts with http://)
• MessageID int - the message ID of the message in the forum
• Subject string
• Body string
• DateCreated date - the date the message was created
• AuthorMemberID int - member ID of the author of the message
• AuthorName string - the name of the author

A sample application is provided to show you all the above functions, so you won't have any issue using our Site Integration Package.

Table of contents

1. Content in this package
2. Installation of the sample application
• Things you need to know before using the Membership Provider..
• Things you need to know before using the Role Provider..
• Upload files to your server
3. Installation of the core files on your site
   • The Files you must upload
   • Achieving Single-Sign-On
   • More information regarding Membership Provider

1. Content in this package

• ASP.NET folder: The sample application showcasing the capabilities of this membership provider. You do not have to learn additional stuff in order to use this membership provider, other than the standard ASP.NET methods
  • bin folder: This folder contains 2 sets of dll's - the membership provider and the forum business logic dll (just like the one in the forum's installation)
  • web.config file: This is a standard web.config file with the ASP.NET version 3.5 framework items and a few key declarations for our membership provider. You don't have to use it, as I will provide you the details that you need to insert into your own web.config to begin using our membership provider.
• readme.htm: This file

2. Installation of the sample application

• Things you need to know before you use the Membership Provider

  • This Membership Provider inherits the System.Web.Security.MembershipProivder class and overrides all of its standard methods without adding any additional methods / properties. It behaves just like the standard ASP.NET SqlMembershipProvider, with the following exceptions (a list of unsupported features):

    1. Setting / Changing Password Question & Answer - not supported in the forum.
    2. Password Retrieval - not supported; we only store password in MD5 hashed format in the forum.
    3. Setting Password Attempt and lock out Window - not supported in the forum.
    4. Member's Last Lockout Date - not supported in the forum.
    5. Members' Last Password Change Date - not supported in the forum.
    6. Specifying Connection String Name - Must be named ForumSoftwareConnection just like in the forum.
    7. Changing User Name - User Name can be changed in the forum's admin control panel.
    8. Supplying ProviderUserKey when creating a user - the key is auto generated when user registers successfully; the key will be the member ID in the forum.
    9. Setting UserIsOnlineWindow for the provider - this will be the same as the forum's setting, i.e., the session timeout setting set for the forum in the forum's web.config file.
  • Your forum application must have its EnableMembershipIntegration (found in forum's web.config file) set to false. In other words, you cannot use this membership provider when the forum is already set up to interact with another membership provider. Another way to say it is this:
    • THIS CAN't WORK: This Membership Provider <-> Forum <-> Another Membership Provider
    • So, if you already have a working membership provider that interacts with the forum, don't use this.

• Things you need to know before using the Role Provider

  • Role <-> User Group are interchangeable terms in our forum software. Role is a special term in ASP.NET, while User Group is a special term in our software. They are the same thing in this software.
  • The Role Provider inherits the System.Web.Security.RoleProvider class and overrides all of its standard methods without adding any additional methods / properties. It behaves just like the standard ASP.NET RoleProvider, with the following exceptions (a list of unsupported features):
    1. CreateRole - not supported in this provider due to the complexity of the User Group system in our software. There are many properties a User Group has in our forum (not just a mere container of members). Simply adding a User Group using this function means nothing in terms of functionality because eventually you still have to go to the Admin Control Panel to set permissions (adding it to forums, galleries etc) for a User Group to actually mean something for you.
    2. DeleteRole - again, due to the same reason as above.
  • both functions can be performed using the Admin Control Panel of the forum.

• Upload files to your server

1. Create a folder on your server (name doesn't matter) where you plan to install the sample application, if you haven't already done so.
2. The software requires its own bin folder, so you will need to mark the forum folder you just created (or existing) on your server as an Application (not just a plain folder), if you haven't done so. This can be accomplished using either the IIS Manager directly on the server, or the control panel your host provides.
3. The sample software supports either ASP.NET 2.0 OR ASP.NET 3.5.
• NOTE: Beginning the next minor version (3.1), we will support ASP.NET 3.5 only. So, it is recommended that you begin to use ASP.NET 3.5 if you haven't done so. You can download the 3.5 framework from Microsoft's ASP.NET site. .NET 3.5 is totally compatible with .NET 2.0, so there is no good reason not to upgrade. The .NET 2.0 framework compatible dll set is provided only for this version (3.0.x) of forum software.
4. Inside the ASP.NET folder, open the web.config file and look for this block of code (close to top; use your editor's Find feature to locate the word "appSettings"):
   
   • DBName : The same value you set for the forum.
   • DBOwnerPrefix : The same value you set for the forum.
   • EnableMembershipIntegration: this must be set to false.
   • ErrorLogFolder : This will be the sample application's ~/upfiles/logs/, not the forum's. In other words, the system will log issues in the sample application, independent from the forum. So, make sure you set the ASP.NET's account's permission to Modify for the folder you specified here.
   • EnableMailLogging : value specified does not matter, but must be present.
5. Look for another section called "connectionStrings" (right below the "appSettings" section):
   
   • Do not change the name ForumSoftwareConnection to anything else. This is the name that our provider looks for.
   • connectionString : Enter the connection string to use connect to your forum database. The format is (italicized portion must be changed to match your own database setting) :
     Initial Catalog=DatabaseName; data source=ServerNameOrIP; User ID=UserName; Password=Password;
     for example: Initial Catalog=ForumDB; data source=localhost; User ID=sa; Password=123456;
   • DatabaseName in the connectionString should be exactly the same as the DBName you specified earlier in the "appSettings" section.
6. Look for another section called "membership" under "system.web"
   
   
• This section is the declaration of our membership provider. Due to the limitations specified above, you can only change
  • minRequiredPasswordLength
  • minRequiredNonalphanumericCharacters
  • passwordStrengthRegularExpression: Refer to MSDN for more information.
  • forumUpfileFolderPath: this is a special parameter not found in the original specification of the ASP.NET's membership provider. The reason we need this one is that this membership provider allows deleting users outside the forum, and when we a user we want to also remove the files uploaded to the forum by this user. Since your site will be a standalone web application like the forum, we cannot use Server.Mappath on your site to find a folder inside the forum application. So, you need to specify the absolute path to the forum's upfiles folder, beginning with the local drive letter. I leave my own value for you as a reference. Make sure you change it to match your forum installation.
    
7. You will also see a section called "roleManager"
   
• with the above setting, the role provider is enabled.
• you can leave the section intact while disabling the role provider by setting the "enabled" attribute to "false".
8. The Message Extractor class does not have a section in the web.config page. Please refer to message.aspx to see the detailed usage. There are 2 event handlers in the code behind.
9. Save the web.config file, and use your FTP client, upload everything in the ASP.NET folder onto the sample application folder on the server (retaining the directory structure). You don't need to upload the ASP.NET folder itself, just the content inside it.
   

3. Installation of the core files on your site

   • The Files you must upload:
     • If you already have a web.config file for your site (most likely you already have one), make sure you copy the web.config sections mentioned above to your own web.config file.
     • The 2 sets of dll's in the bin folder - must be uploaded to your own bin folder. The ASPPGForumLogic.dll/pdb files are the same as the one contained in the 3.0.1 version.
   • Achieving Single-Sign-On:
     • In order to achieve single sign on, in addition to using this membership provider, you will need to enable cookie based forms authentication for your site, as the forum uses forms authentication to recognize logged in users.
     • In order to get the forms authentication ticket to be recognized on both the forum and your site, you need to make sure that in both web.config files:
       • forms authentication cookie's name, protection, path are the same.
       • you have identical machine key specified (validationKey, validation, decryptionKey)
         • You can come to this site for help if you don't know how to generate machine key.
   • More Info regarding Membership Provider
     • MSDN - detailed examples and reference
     • 4GuysFromRolla - detailed explanation on the provider model and everything