Creating the Model
This tutorial explains how to make the Model for a project in .NET. This tutorial presumes that you are writing an application which needs to store objects to a database, and that you have already designed all the classes, attributes, and relations between the classes.
It is highly recommended that your model be a separate project, not only because it is good practice, but also it allows you to easily compile your model into a DLL which can then be used to generate the SQL to create the database (more on that later).
So, the first step is to add a Class Library to your application, perhaps with the name Model. After adding a reference to Shunde, you simply start adding your class files.
There are two ways to create class files for your Shunde project: manually writing them, or generating them from a webpage. This page concentrates on the first method as it is useful to know how the files work.
A Shunde model file has the following general layout:
- Declaration of the classname, which extends a DBObject type
- Private fields (strings, integers, other DBObjects) which correspond to database columns (note that these must be private for Shunde to work)
- Public get and set methods to access the private fields
- A static constructor. A static constructor is called when the object is first loaded by .NET and allows the instantiation of static variables. Shunde has an internal static variable which is a Dictionary holding all the ObjectInfo objects for all objects. The static constructor of an object defines which fields correspond to database columns, and gives this information to Shunde.
- No constructor is normally used (or, more accurately, the default constructor which takes no parameters is used). If you add a constructor, you must make sure you include a constructor with no parameters, as Shunde needs to be able to instantiate your class dynamically, and it presumes there are no paramaters,
- Any instance methods follow, which do operations on the fields
- Static methods for returning arrays of this object class usually follow.
The following useful methods and properties are inherited from DBObject:
- ID - an integer which uniquely identifies your object. When you create a new object and save it, a new ID is automatically generated for it.
- Populate() - a method which populates the fields with data from the database - it presumes the ID of the object has been set.
- Save() - either creates a new object in the database or updates an existing object.
- Plus some others which we'll go into later...
So, to use an example from another page, we will define a car object:
using System;
using Shunde.Framework;
namespace TestSpace
{
/// <summary>
/// A Car object
/// </summary>
public class Car : DBObject
{
private string make;
/// <summary>The make of the car</summary>
public string Make
{
get { return this.make; }
set { this.make = value; }
}
private int year;
/// <summary>The year made</summary>
public int Year
{
get { return this.year; }
set { this.year = value; }
}
private Person owner;
/// <summary>The owner of the car</summary>
public Person Owner
{
get { return this.owner; }
set { this.owner = value; }
}
private string description;
/// <summary>A description of the car in full</summary>
public string Description
{
get { return this.description; }
set { this.description = value; }
}
private bool isConvertible;
/// <summary>Specifies whether or not this car is a convertible</summary>
public bool IsConvertible
{
get { return this.isConvertible; }
set { this.isConvertible = value; }
}
/// <summary>Sets up the ObjectInfo for this class</summary>
static Car()
{
// Create the table for the Car object, with the following columns:
DBTable tbl = new DBTable("Car", new DBColumn[] {
// The make of the car, a string between 1 and 50 (inclusive) characters long
new DBColumn( "make", typeof(string), 1, 50 ),
// The year the car was made, an integer that cannot be null, and must be at least 1900
new DBColumn( "year", typeof(int), false, 1900, null ),
// The owner of the car, which is a Person object, which extends DBObject
new DBColumn( "owner", typeof(Person), false ),
// A string which holds a general description, which can be null.
// Because we do not specify minimum and maximum lengths, this becomes
// a multiline text (an ntext column in SQL Server) which can hold
// huge amounts of text
new DBColumn( "description", typeof(string), true ),
// A boolean. A boolean can never be null
new DBColumn( "isConvertible", typeof(bool), false )
});
// Tell the Shunde Framework about this object
ObjectInfo.RegisterObjectInfo(typeof(Car), tbl);
}
/// <summary>Gets all the Car objects in the database</summary>
public static Car[] GetCars()
{
Type t = typeof(Car);
ObjectInfo oi = ObjectInfo.GetObjectInfo(t);
string sql = oi.GetSelectStatement() + " WHERE [DBObject].[isDeleted] = 0 ORDER BY [DBObject].[displayOrder] ASC";
return (Car[])DBObject.GetObjects(sql, t);
}
/// <summary>Gets all the Car objects in the database filtered by the given <see cref="Person">owner</see></summary>
/// <param name="owner">The Person to filter by</param>
public static Car[] GetCars(Person owner)
{
Type t = typeof(Car);
ObjectInfo oi = ObjectInfo.GetObjectInfo(t);
string sql = oi.GetSelectStatement() + " WHERE [DBObject].[isDeleted] = 0 AND [Car].[ownerId] = " + owner.Id + " ORDER BY [DBObject].[displayOrder] ASC";
return (Car[])DBObject.GetObjects(sql, t);
}
}
}
As you can see, in the static method you need to tell the Shunde framework about the table and the columns in the table for this object. For detailed information on defining columns, click here.
The two static GetCars methods show how to retrieve an array of objects from the database. The basic idea is that we get the ObjectInfo about the object from the Shunde framework which allows us to access an SQL statement which contains "SELECT ... FROM ... " including all joins etc. We then (optionally) append the WHERE clause. This will normally at least exclude deleted objects (note objects in Shunde are never deleted; they are just marked as deleted), or filter by some parameter, as in the second method.
|
