Optionally provide private feedback to help us improve this article...

Thank you for your feedback!


Creating Users Programmatically

The code below shows how to create, update & authenticate users programmatically using the InstantForum .NET API.

If your looking to offer a single sign on experience to your users you would typically need to add users to the InstantForum tables during your main web site registration process. The code examples in this article should help.

To take advantage of the InstantForum .NET API from your .NET projects please read Using the InstantForum .NET API.

Adding & Authenticating User

// build a new user
InstantASP.InstantForum.Components.User newUser = new InstantASP.InstantForum.Components.User();
newUser.Username = "New Username";
newUser.EmailAddress = "new@email.com";
newUser.Password = "pa$$w07d#1";
newUser.PrimaryRoleID = InstantASP.Common.Business.Roles.SelectRole(InstantASP.Common.Enumerations.EnumRequiredRoles.Member).RoleID;
newUser.TimeZoneOffset = 0;
	 
// insert user
int newUserID = InstantASP.InstantForum.Business.User.InsertUpdateUser(newUser);

// was the insert successful?
if (newUserID > 0)
{
	// get instance of user & authenticate
	InstantASP.InstantForum.Components.User user =
		new InstantASP.InstantForum.Components.User(newUserID);
	if (user.UserID > 0)
	{
		user.Authenticate(true);
	}
}
else
{
	if (newUserID == -1)
	{
		// username already exists 
		// usernames must be unique for each user within the InstantASP_Users table
	}
	else if (newUserID == -2)
	{
		// email already exists
		// emails must be unique for each user within the InstantASP_Users table
	}
}

Authenticating a User Via the API

You can pass the username, email address or user ID for any user into the InstantForum.Components.User constructor to return an instance of that user. You can then call the Authenticate method on the user object to create the necessary forms authentication cookie to persist the user authentication. For example...

InstantASP.InstantForum.Components.User user = new InstantASP.InstantForum.Components.User("user@email.com");
user.Authenticate(true);

If you wanted to validate user credentials and then authenticate a user you can use the following code...

string username = "Example Username";
string email = "email@address.com";
string password = "pa$$w07d#1";

// check email & password match
int userId = InstantASP.Common.Business.UserRepository.ValidateUser(email, password, Common.Enumerations.EnumLoginUsing.EmailAddress);

// if successful the UserID will be returned
if (userId > 0)
{

	// get instance of user from returned UserID & call 
	// User.Authenticate to generate the forms authentication 
	// cookie to persist user authentication
	InstantASP.InstantForum.Components.User user =
		new InstantASP.InstantForum.Components.User(userId);
	if (user.UserID > 0)
	{
		user.Authenticate(true);
	}

}

User.Authenticate()

When you call the Authenticate method on the User object this will create a client side forms authentication cookie to persist authenticate for that user within our software. If you don't supply any parameters to the Authenticate method this will create a session based forms authentication cookie which will expire when the client closes there browser. If you supply a Boolean like so User.Authenticate(true) thiswill create a cookie that will last for 1 year from the date you called User.Authenticate();

The forms authentication cookie generated by the call to User.Authenticate() can be configured through the regular <authentication> element within your applications web.config. For example the following <authentication> element would create a forms authentication cookie with the name "InstantASP" and the domain "instantasp.co.uk"...

<authentication mode="Forms">
<forms name="InstantASP" domain="instantasp.co.uk" cookieless="UseCookies" loginurl="Logon.aspx" protection="All" slidingexpiration="true" path="/">
</forms> </authentication>

For single sign on (SSO) to work you must share the forms authentication ticket across the applications you wish to allow SSO. For further information on sharing the forms authentication cookie please see InstantForum Single Sign On Considerations.

IMPORTANT: If you already generated a forms authentication cookie within your application for example by calling FormsAuthentication.SetAuthCookie() you don't need to call the User.Authenticate() method within our API. Our User.Authenticate() method simply gnerates the forms authentication cookie and is redundent if you already create a forms authentication cookie during your login or registration process.

Updating a User via the API

Lets say we have a user with the email john@doh.com. If we want to update this users username you can accomplish this with the following code...

InstantASP.InstantForum.Components.User existingUser = 
	new InstantASP.InstantForum.Components.User("john@doh.com");

if (existingUser.UserID > 0)
{

	existingUser.Username = "John Doe";
	existingUser.PostSignature = "Regards,<br/><br/>John Doe";

	int updatedUserID = InstantASP.InstantForum.Business.User.InsertUpdateUser(existingUser);
	if (updatedUserID > 0)
	{
		// update was successful               
	}
	else
	{
		if (updatedUserID == -1)
		{
			// username already exists 
			// usernames must be unique for each user within the InstantASP_Users table
		}
		else if (updatedUserID == -2)
		{
			// email already exists
			// emails must be unique for each user within the InstantASP_Users table
		}
	}
}

Logging Out

The call below will delete the users forms authentication client side cookie and will log them out of the forum...

InstantASP.Common.Security.FormsAuth.DeleteTicket()