Extending the Application User¶
Introduction¶
This How-To will explain how to Extend the ApplicationUser
class. But first, let's see what this class is.
The ApplicationUser
is a class, pre-designed and created by the Web Application Template that is used as the main User object of your Application.
In other words, this is the class used for:
- Authentication
- Authorization
- Permission and Role Management
- Application Actions Management
- Auditing
- Profiles Management
- Locales, Languages and other Settings Management
- Any other logic that applies to an account using your Application
The class itself has multiple Attributes, as well as relationships with several classes:
As you can see, anything that has to do with the aforementioned built-in functionality is already there. However, what if you need something more? For example, what if you want to keep information such as the Social Security Number, Date of Birth, Favorite Beer (no?) for your Application's Users?
One would think "hey, I'll just go and add some new attributes to the ApplicationUser
class, right? Sorry, no. Unfortunately, the ApplicationUser
class, as well as all its related classes are Systemic classes, meaning that you cannot alter it. What you can do, however, is extend it, by creating your own user class that inherits all the properties of the ApplicationUser
class and then utilize your new Class to add any additional properties you might need.
Extending the Application User¶
To Extend the ApplicationUser
class, follow these simple steps:
- Create your own Class that you will use are your user. (In this example, I'll name mine: User. Surprising, huh?)
- Make sure your new Class is selected. Check out its properties in the Property Grid of the Business Objects Editor
- Find the Base Class Property
- Select the
ApplicationUser
Class as the Base Class of your new Class
As soon as you do that, you will see your new class filled with all the Properties inherited from the ApplicationUser
, like so:
From this point, you can:
- Remove the
Id
property, added by the new Class you created earlier. Not that it would do you any harm, but since your Primary Key will still be theUserName
, no need to confuse you or your fellow Developers with an additionalId
column. Should you decide to keep this Attribute, at least post a Note to remind your team that thisId
is not the actual Key of your class. Help contain the maddness. - Add any attributes you want to your new, extended class and enjoy your
User
class with both its previous comprehensive functionalities and all your new properties and methods
Modifying the Existing Code¶
Now that you have your own User class, you'll probably want to revisit your Forms that manage it. The Web Application Template has two forms already created and installed that manage the users:
- UsersList
- ManageUser
- CreateAdmin
The aforementioned forms are using the systemic ApplicationUser
Class to List all the saved users as well as provide functionalities to create new ones, edit the existing ones or delete the ones you no longer like that much.
If you are reading this How-To, chances are, you will want to change this form to manage your own extended user class, say the User
created earlier as an example. To, you will need to revisit these forms and make them
work with this extended class.
To do that, follow these simple steps:
todo: UsersList
- Open the UsersList Form
- Locate the DataSet used in the List presenting your application's Users. You will see it is using the
ApplicationUser
Class - Select your own Class as this Dataset's Class
- Save the Form. You're good here
todo: ManageUser
- Open the ManageUser Form
- Locate its Model
- Change the
ApplicationUser: ApplicationUser
Model Object toApplicationUser: User
(or, simply, leave the name of the object as it is and change the Datatype of the object to the class you just created, representing the user in your Application)
- Go to the Controller tab to edit the functionality of your Form
- Find the NewUser Action. Change the
Domain.ApplicationUser.Create()
code to:Domain.User.Create()
(or toDomain.YOUR_CLASS.Create()
) - Find the EditUser Action. Change the
Domain.ApplicationUser.GetByKey(Id)
code to:Domain.User.GetByKey(Id)
(or toDomain.ApplicationUser.YOUR_CLASS(Id)
)
todo: CreateAdmin
- Open the CreateAdmin Form
- Locate its Create Controller Action
- Change the
Domain.ApplicationUser adminUser;
line toDomain.User adminUser;
line
At this point, you will have your own, fully functional, comprehensive User class that you can use however you deem fit! Go crazy.
Extended Application User & Authentication¶
Hint
If your Application uses a simple Form Authentication, or you're brave enough to not use any at all, feel free to move past this section altogether.
This section will cover important things you will need to know when working with Extended ApplicationUser
Classes and Applications that use Authentications such as:
- OS Authentication
- Google Authentication
- Facebook Authentication
OS Authentication¶
If you choose OS Authentication for your Application, you can define which User class will represent your User when logging into your App, as shown here. The User class can be:
- Either the
ApplicationUser
class, which is the systemic class described before, and will be set by default if you do not choose any other - Either the extended User Class you create by extending the
ApplicationUser
class (e.g.User
class that extends theApplicationUser
) - Or a further extension of your extended
ApplicationUser
class (e.g.LinuxUser
class, that extends theUser
class, extending theApplicationUser
class and so on)
External Authentication¶
Should you choose Forms Authentication and add some External Authentication methods such as Google or Facebook, you will be able to select the User class to represent your User when registering into your app, as shown
here. As mentioned before with the OS Authentication, the selected User class can be the ApplicationUser
, a class extending the ApplicationUser
or any further extension you would like to use.
Important Notes¶
Now, pay attention.
In both cases (OS and External Authentication), objects of your extended Classes will be created and saved into your Application Database.
In order for such a process to be completed successfully, you must remember one thing:
Warning
Never assosiate your extended Application User classes with required associations.
For example, imagine you want each User to be associated with a Phone Number. Since the User is an Extension of a class that will be created Automatically every time a User is logged in or registed into the system, the association should be optional
If you don't believe me, believe this: if you create a mandatory association (1-1) then as soon as the User object is created and stored into the Database, it will require a Phone Number. However... the Phone Number will be null at that point (since the User object will be created automatically by the OS or an External Provider). The Save process will throw an exception, the user registering at that moment will see that exception, get sad, maybe write you a letter of complaint, then you will get sad and so on and so forth.