Sitefinity CMS
Contents
Implementing Data Access with Nolics.NET Send comments on this topic.
See Also
Developing with Sitefinity > Data Access > Nolics.NET Examples > Implementing Data Access with Nolics.NET

Glossary Item Box

Overview

Data access in Sitefinity uses Nolics.net 2005 - a domain-specific language (DSL) object relational mapping tool. Nolics.net 2005 then automatically generates code and classes that provide the functionality for interfacing with the database, creating instance of the data objects, and data operations like insert, update, and so on.

 

What Is a Domain Specific Language?

A domain-specific programming language is designed to solve problems in a particular domain and is not intended to solve problems outside of it. In contrast, general purpose programming languages like Visual Basic or C# were created to solve problems in many domains. Nolics.net is a DSL that solves the problem of performing data operations like select, insert, update, and so on.

 

Working with Nolics.net 2005

Nolics.net 2005 is a DSL that integrates into Visual Studio and provides functionality for defining and persisting objects to a data store such as SQL Server 2005. The two main aspects to Nolics.net are:

  • Defining object persistence 
  • Defining the behaviors for the object

 

The overview below is intended only as an introduction. The  Nolics.NET 2005 Developer Guide provides further details and reference information. In addition, visit the Domain Specific Language Tools section of the Microsoft MSDN Web site.

 

Refer to the Sitefinity licensing agreement to determine if a Nolics.net 2005 development license is included in your version. If not, a trial version of Nolics.net 2005 could be downloaded to determine whether or not to use it for data access in your custom module.

 

Getting Started with Nolics.net

All of the logic defining the data structure and behaviors for the objects used in a custom module is contained in data definition classes, implemented using Nolics.net 2005 domain-specific language. The .dbclass file (Job.dbclass) contains the object definition; the .Designer.cs (Job.Designer.cs) file contains the generated code generated by Nolics.net based upon the .dbclass file and the companion partial class (Job.cs) containing the behaviors. Figure 1 illustrates the Nolics.net files:

Nolics files.

Figure 1

 

The actual database objects (that is, tables, stored procedures, and so on) are generated by Nolics.net from the .dbclass file data structure definitions. Therefore, it is not necessary to create or modify database objects like tables and stored procedures directly. Details could be found in the Upgrading the Database section below. 

Do not manually create or alter any database objects (tables, stored procedures, and so on) related to the object definitions. They are maintained by Nolics.net 2005. Sitefinity will automatically verify and upgrade the database for an installed custom module.

 

Creating a Database Class

The first step is to define the data structures using the Nolics.net domain-specific language. This language will be used to generate the source code representing the objects that will contain the data retrieved from the database:

  1. Right-click on the folder where the data definition class (.dbclass) file will be located.
  2. From the context menu, select Add New Item.
  3. From the list of templates, select Nolics.net Database Class. Figure 2 demonstrates how to add Nolics.net database class file in Visual Studio:

     

    Figure 2                                                                                                                                                                               

     

  4. Enter the name of the new class, and then click Add.
  5. A new .dbclass definition file is created as shown in Figure 3  

                                                                                      

         The two .dbclass files.

           Figure 3

 

When the new .dbclass file is created there are actually two files: the .dbclass file containing the domain-specific Nolics.net code, and a companion .Designer.cs file which contains the source code generated by Nolics.net. DO NOT MAKE CHANGES TO THIS FILE! It is re-generated whenever changes are made to the .dbclass file and your changes will be overwritten.

 

 

Persistent Data Definitions

The definition for the persistent data objects is defined in classes using a Nolics.net domain-specific language. This definition is a hybrid of property definitions for an object and column definitions in a database. The following example shows the definition of the data structure for a Job in the sample Job.dbclass file:

Job.dbclass Copy Code
/// <summary>
/// Definition of the Job object data.
/// </summary>
dbclass Job [TableName="sf_Jobs_Job"]
{
   primary key guid ID[AutoGenGUID=True];
   string JobName[Length=100];
   string Description;
   bool Active;
   modified date DatePosted;
}

 

The data structures are analogous to defining a table structure because each data element is given a name and data type. In addition, relationships between objects could be defined much like primary key-to-foreign key relationships between database tables. For example, in the sample Jobs module, the Job Type object is related to the Job object using a Nolics.net link. This information is used to generate the table in the database and code in the .Designer.cs file. The Nolics.NET 2005 Developer Guide  and  Nolics.net 2005 provide many more details on this important topic.

Nolics.net maintains all the database objects such as tables, stored procedures, and so on, based upon the definition of the persistent data objects. Do not manually change any database objects. Whenever changes are made to the persistent object classes Nolics.net will automatically update the database overwriting any changes made manually.

 

Query Definitions

In addition to defining data structures, queries could be defined for accessing data. There are two kinds of queries: static and dynamic. A sample static query is shown below for querying active jobs:

[C#] Copy Code
/// <summary>
/// Get a collection of all active jobs sort by date posted.
/// </summary>
query GetActiveJobs for Job [ProcedureName = "sf_Job_GetActiveJobs",OrderBy="DatePosted DESC"]
{
 string Title ?like Title;
}

 

This is a static query, that is, a query where the number and type of parameters cannot be changed at execution time. Dynamic queries are also available, which allow the number and type of parameters to be defined at execution time. This information is used to generate the stored procedure in the database and code in the .Designer.cs file. 

 

It is important to note that a query returns a collection of objects (in this example a collection of Job objects). Nolics.net handles the retrieval, instantiation, and population of each Job object when the collection is created.

 

There are numerous options to consider when defining persistent objects and queries to provide maximum flexibility which are covered in detail in the Nolics.NET 2005 Developer Guide.

 

 

Defining Behaviors for the Object

Behaviors for objects are defined by implementing methods based upon standard interfaces. These interfaces handle events related to object persistence. The following table lists the standard events and the corresponding interface:

Event Interface Description
Create IOdbEventCreate Called when an object is created.
Delete IOdbEventDelete Called when an object is deleted.
Verify (Validation) IOdbEventVerify Called before an object is saved.
Persist IOdbEventPersist Called when an object is loaded or saved.

 

To implement one or more of these behaviors, a partial class is created based upon one or more corresponding interfaces. The following example from the Job.cs file contains an implementation of the Create interface which is called when a new object is created. This could be used to set default values of properties and other operations:

Job.cs Copy Code
partial class Job: IOdbEventCreate
{
 public void CreateObject(OdbDataProvider provider)
 {
   //Logic while creating the object
 }
}

All of the interfaces are optional, so only implement those where you need functionality during that event, that is, creating an object.

 

Implementing Associated Business Logic

In addition to defining standard behaviors, the partial class could contain any additional business logic (methods, properties, and so on) as required by the application architecture. For example, if you needed some complex validation when saving data in an object, you might add several private methods to the partial class and then call them from the Verify event.

 

Using Data Objects in Your Code

Once the data objects are defined, instances can be created as with other objects. The following example shows how to create an instance of the Job class:

Copy Code
Job job =  new Job();

 

Once an instance is created, it could be used in conjunction with a variety of Nolics.net classes and methods for standard data operations like selecting, inserting, updating, and deleting data.

It is important to note that all of the data operations are handled transparently by Nolics.net. You only interact with the object using the Nolics.net classes and methods.

 

Using OdbClass for Data Operations

OdbClass is a static Nolics.net 2005 class that is used for a variety of regular operations like joining objects to transactions and loading data. The following example demonstrates how to create a new instance of a Job object utilizing OdbClass. All Nolics.net methods utilize a transaction.

 

In this example, the CreateJob method creates a new job and returns a reference of the newly created job object. The transaction parameter is a reference to a transaction to be used for the operation. Note that the actual creation occurs when the transaction associated with the job is committed.

[C#] Copy Code
public override Job CreateJob(Transaction transaction)
{
 //There must be a transaction to complete the operation.
 if (transaction == null)
 {
   throw new ArgumentNullException("Transaction is null for creating a job.");
 }
 //Create (insert) the new job object.
 Job job = new Job();
 OdbClass.Create(job, transaction);
 return job;
}

 

Transactions in Nolics.net 2005

Nolics.net 2005 requires each object to be associated with an object level transaction before it could be inserted, updated, or deleted. Therefore, after creating an instance of a class the object must be associated with a transaction using the OdbClass.Create() static method.

[C#] Copy Code
Transaction transaction = new Transaction();
Job job = new Job();
OdbClass.Create(job, transaction);

 

Before an object is associated with a transaction it must have a primary key which can either be auto-generated in the persisted object definition or manually assigned to the instance of the object before joining it to the transaction.

 

Existing data could be loaded into an object instance and joined to a transaction.

[C#] Copy Code
Job job = new Job();
job.ID = id;
OdbClass.LoadByPrimaryKey(job);
//Add the job to a Nolics.net transaction (required)
transaction.Join(job);

 

The Nolics.NET 2005 Developer Guide  and  Nolics.net 2005 provide many more details on this important topic.

 

Upgrading the Database During Development

The database objects in a custom module are automatically created in the database when the module is loaded by Sitefinity. However, it may be helpful to manually invoke a database upgrade to create the objects during development. Figure 4 illustrates upgrading the database with the Nolics.net definitions.  Follow the steps:

 

Upgrading the database with the Nolics.net definitions.

Figure 4

 

  1. Right-click on the custom module project node in the Solution Explorer.
  2. Select  Upgrade Database(s).
  3. Select the .config file to use for the upgrade.
  4. Either select Check to step through the upgrade steps, or Upgrade to perform the entire upgrade. 

 

The Check option in step #4 is a good way to learn how the upgrade process works.

 

Creating a Configuration File for Upgrading the Database

To upgrade the database there needs to be a separate App.config file located in the data access project. To create an App.config file and set the Nolics.net connection string, use the following steps:

  1. Right-click on the Data Access Class Library project file in the Solution Explorer and select Add New Item.
  2. Select Application Configuration File, and then click Add.

     

    Figure 5 

     

  3. From the Tools menu, select Edit Connections. (See Figure 6)

     

    Edit Configuration option.
    Figure 6

     

  4. Select the App.config file from the list of configuration files in the solution. (See Figure 7)

     

    Figure 7

     

  5. Verify the connection string information using the Connection Editor. (See Figure 8)

     

    Figure 8

     

 

The Sitefinity SQL Server 2005 database is located in the /App_Data folder of the Sitefinity Web site by default.

 

See Also