NHibernate Model-First Tutorial

Creating a Model Using Model-First Approach

This section explains how to create a model using the Model-First approach.

To create a model using the Model-First approach, perform the following sequence of actions:

1. In the Solution Explorer window, right-click the name of your project.

2. From the shortcut menu, select the Add command and select the New Item option. 
   

   
   

3. In the Installed Templates column of the Add New Item window, select Data.

4. In the central column of the Add New Item window, select Devart NHibernate Model.

5. Click Add.
   

   
   

6. On the Create Model Wizard welcome page, select Model First and click Next.
   

   
   

7. On the Model properties page, select identity from the Name drop-down list in the Default Identity Generator area, define the settings of your model and click Next.
   

   
   

8. On the Choose Code Generation Template page, select the appropriate template and click Next.

9. On the final window of the wizard click Finish.

After the empty diagram space is displayed, you can proceed to creating required classes, associations and inheritances.

The description of procedures for creating classes, associations and inheritances for the model is provided below.

Creating a Class

This procedure explains how to create a class. For the purpose of this example, we shall create the Blog class (see the picture below).

Note: Before proceeding to creating classes, check that in the properties of your model identity is selected as the default generator. For this purpose, in the Model Explorer window, right-click your model, select Properties from the shortcut menu, and, in the Properties window, check that Default Identity Generator is set to identity.

1. Right-click on the empty diagram space and select Add Class from the shortcut menu.
   

   
   

2. Click the default name of the class (Class1), enter Blog and press Enter.

3. Right-click the created class and select Add property from the shortcut menu.
   

   
   

4. In the Name box, enter the name of the property (BlogID).

5. From the Type drop-down list, select Int64.

6. Select the Primary Key check box.

7. (Optional) To change the default parameters of the database column, to which this property is to be mapped, click the three-dotted button in the Column field and, in the Column Editor window (see below), enter the desired values of the parameters and click OK.
   

   
   

   Note: This page may differ from the one pictured above, depending on the type of the selected property.

8. Click OK.

9. To create the second property (BlogTitle),  right-click the created class and select Add property from the shortcut menu.

10. In the Name box, enter the name of the property (BlogTitle).

11. From the Type drop-down list, select String.

12. (Optional) To change the default parameters of the database column, to which this property is to be mapped, click the three-dotted button in the Column field and, in the Column Editor window (see above), enter the desired values of the parameters and click OK.

13. Leave the other settings as they are and click OK.

    All the other classes in the model are created similarly.

Creating an Association

This procedure describes how to create an association. For the purpose of this procedure we suppose that at least the Blog and Post classes have been created (see the picture of the example model in the Creating a Model Using Model-First Approach section). The association that is created in this procedure is of the One-to-Many type.

To create an association, perform the following sequence of actions:

1. On the model diagram, right-click the Blog  class and, from the shortcut menu, select Add association.
   

   
   

2. In the End 1 area, set Class to Blog, Multiplicity to 1 (One) and leave other settings set to their default values.

3. In the End 2 area, set Class to Post, Multiplicity to * (Many) and leave other settings set to their default values.

4. (Optional) To create an association using a unique property instead of the primary key, under Foreign key references, select Unique property of Blog and from the drop-down list select the required unique property.

5. (Optional) To change the default parameters of the database column, in the Columns mapping area, click the three-dotted button in the Column field and, in the Column Editor window, enter the desired values of the parameters and click OK.

6. On the Association editor page, click OK.

Creating an Inheritance

This procedure describes how to create an inheritance. For the purpose of this procedure we suppose that the Author and RegularAuthor classes have already been created (see the picture of the example model in the Creating a Model Using Model-First Approach section). The inheritance that is created in this procedure is of the Table-per-Hierarchy type.

To create an inheritance, perform the following sequence of actions:

1. On the model diagram, right-click the Author class and, from the shortcut menu, select Add inheritance.
   

   
   

2. From the Base Class drop-down list, select Author.

3. From the Derived Class drop-down list, select RegularAuthor.

4. From the Type drop-down list, select Table Per Hierarchy.

5. In the For Base Class box of the Discriminator Value area, specify the value for the base class (for example, "0")

6. In the For Derived Class box of the Discriminator Value area, specify the value for the derived class (for example, "1") .

7. In the Discriminator area, select either Column or Formula and, from the Type drop-down list, select the appropriate type. If Column is selected, you can change the default settings of the column by clicking the clicking the three-dotted button in the Column box and specifying the required values on the Column editor page.

8. Leave the other settings set to their default values.

9. Click OK.

Summary Description of the Model

The resulting model should contain the following items:

• Classes:
  • Blog;
  • BlogRoll;
  • Author;
  • RegularAuthor;
  • GuestAuthor;
  • Post;
  • Category.
• Associations:
  • Blog - Post, Blog - BlogRoll (one-to-many);
  • Blog - Author (one-to-one);
  • Category - Post (many-to-many).
• Inheritances:
  • Author - Regular Author;
  • Author - Guest Author.

Below is the example of the resulting model:

Mapping and Code Generation Setup

This section explains how to set up mapping and code generation in NHibernate models.

For the purpose of mapping and code generation, you may need to create and define folders, into which mapping and generated code will be saved, as well as other parameters available in the Properties window of the selected template.

The definition of output folders for mapping and code generation is optional, if such folders are of no importance for you, go directly to Step 11 of the procedure.

To define folders for mapping and code generation, perform the following sequence of actions:

1. In your project in the Solution Explorer window,  create a folder for mapping (for example, Mapping) and a folder for generated code (for example, Entities).

2. Navigate to the Model Explorer window, select the template and click to display the Properties window for the selected template.
   

   
   

3. In the Output section of the model properties, click the Entities Output line and then click the displayed three-dotted button. 

4. In the Select Project Folder dialog box, select the appropriate folder for entities (for example, the Entities folder that was created in Step 1 of this procedure) and click OK.

5. Select the appropriate value for the File Per Class property.

6. To enable the entity property validation mechanism in the Validation section locate the Validation Framework row and select the appropriate framework; use the Validation Error Messages row to apply error messages stored in the application resources.

7. In the Xml Mapping section of the template properties, to define the way of mapping file processing during build time select the appropriate value for the Xml Mapping Action property.

8. To generate separate mapping files per class, set the Xml Mapping File Per Class property to True; to generate one mapping file, set this property to False.

9. Click in the Xml Mapping Output line and click the three-dotted line to open the Select Project Folder window.

10. In the Select Project Folder window, select the appropriate folder for entities (for example, the Mapping folder that was created in Step 1 of this procedure) and click OK.

11. (Optional) To specify additional parameters for your application (app.config) or web-application (web.config), for example, to change the Proxy Factory setting, right-click the diagram, select the Model Settings menu item from the shortcut menu and in the tree area select Configuration.
    

    
    

    Note: On mapping and code generation, the NHibernate library is added to the configuration of your application, provided that this library is available from the Global Assembly Collection. If this library is stored elsewhere, in the Solution Explorer window, right-click Reference, select the Add reference command from the shortcut menu and follow the on-screen instructions to add the library to the configuration of your application.

12. To generate code and mapping, save the model.

    Entities and mapping files are successfully generated and stored in the specified folders:

    

Updating the Database from the Model

This section explains how to update the database from the model that has been created using the Model-First approach.

To update the database from the model, perform the following sequence of actions:

1. Select Tools --> Entity Developer --> Update Database from Model.
   

   
   

   Note: Select the Regenerate Storage check box to completely regenerate the whole Model Storage part and Mapping, including the description of storage columns and ends of relations.

   In case of NHibernate, all the customization of Columns options and other mapping settings will be filled automatically using our engine, converting Conceptual model to the Storage model and Mapping between them. The engine considers entities, associations, and inheritances from the Conceptual model.

   When working with NHibernate ORM this option is rarely used because NHibernate runtime does not require the Storage part and Mapping and can work without them. With NHibernate, this option should be used only if you want your Storage part to be always completed, and want it to be done automatically.

2. (Optional) Select the Regenerate Storage check box, if appropriate.

3. Click Next.
   

   
   

   Note: This page may differ from the one pictured above, depending on which provider is selected.

4. On the Set up data connection properties page, specify the connection parameters for your model and click Next.
   

   
   

5. On the Choose schemas page, select one or more schemas to be compared and click Next.
   

   
   

6. On the Choose change actions page, select the appropriate action(s) and click Next.
   

   
   

7. On the View and execute script page, click Execute to execute the displayed scripts.

8. On the final window of the wizard click Finish.

9. To check that the process provided valid results, go View --> Entity Developer and select Database Explorer.
   

   

Testing the Model

 Certain test data must be entered in order to test the correctness of entities and mapping. A sample procedure for entering test data is given below. 

Entering Test Data 

To enter test data, perform the following sequence of actions:

1. In the Database Explorer window (see above), right-click dbo.Blogs and, from the shortcut menu, select Retrieve data.

2. In the Blog Title column of the Data tab, enter "dotConnect", as shown below.
   

   
   

3. In the Database Explorer window, right-click dbo.Posts and, from the shortcut menu, select Retrieve data.

4. Enter the test data, as shown below.
   

   

Creating and Using a New Query

After the test data have been entered, the next stage is to create a new query and use it to test the validity of the model. Data returned on the query must be identical to those entered in the previous procedure.

To create and use a query, perform the following sequence of actions:

1. Go to Tools -> Entity Developer and select New Query.

2. From the Query type drop-down list of the Entity Developer Query toolbar, select HQL.

3. On the displayed Query.eqry tab, enter a new query, for example, "from Blog"

4. On the Entity Developer Query toolbar, click the Run Query button.

5. View the results of the query (shown below).