|
ClassBuilder Documentation
Inside The Base Classes
ClassBuilder Release History
Documentation
Designing your Microsoft SQL Server 2000 database
Create the tables of your database and define your primary and foreign key relationships.
The ClassBuilder relies on these defined relationships to build it's classes.
A Base class and a Child class will be generated for each selected table.
Additionally, any table that has a foreign key relationship will have a collection representing the records in the related table.
For example, if you have a Person table and an Address table and set up a relationship such that a Person can have many Address records,
then the ClassBuilder will generate a Person class containing an Address collection that can be enumerated in the code.
In other words, when you instantiate a Person record, you can easily loop through all of their related Address records with just a few
lines of code.
Using the ClassBuilder
Step 1: Select your SQL Server and Database
- Project: This drop-down list contains previously saved ClassBuilder projects. To begin a new project, choose "-- New Project --" from the list.
- Project Name: Give the ClassBuilder project a name. This is for organizational purposes and won't be reflected in the output code.
- SQL Server: Provide the name of your SQL Server by typing in the name or by using the SQL Server discovery button. If your database has been set up on an Instance other than the default SQL Instance, then provide this using the format: SERVER\INSTANCE.
- Trusted Connection: If you connect to your database using your Windows login, then leave this box checked. Otherwise, uncheck the box and provide your SQL login and password.
- Username: The SQL Username used to connect to your database.
- Password: The SQL Password used to connect to your database.
- Connect (button): Once you have supplied your SQL Server name and the login information, click this button to connect to your SQL Server and populate the list of databases.
- Database: Choose your database from this list.
- Continue (button): When you have selected your database, click this button to continue to Step 2.
- Delete (button): Click this button to delete the ClassBuilder project. No previously output code will be affected.
Step 2: Defining Outputs
- Language: Choose the .NET language for your output code.
- .NET Project Name: The name of the .NET assembly for the project that will contain the output code.
Click the search button to locate the project file.
- Namespace: The name of the namespace that the classes will be placed inside.
This can be an existing namespace in your project, or a new one.
- Connection String: The connection string that the classes will use to connect to your database. This can be a literal string, or supply the name of a function that returns the connection string.
- Copy SqlHelper to: Data access for the classes is contained in a file called SqlHelper and was created by Microsoft. You'll need a copy of this file in your project. Specify the location that you would like this file copied to in your project.
- Copy ErrorHandler to: This file is now obsolete and will be phased out of the interface in a future release.
- Base Class Prefix: The prefix to add to your Base classes. The ClassBuilder creates 2 classes for each table that you select. A Base class and a Child class. The Base class contains the core functionality and provides the actual data access. The Base classes should not be modified. The Child class inherits from the Base class and can contain extended functionality that you provide.
- Create Base Classes: You may choose to output the Base classes as one single code file, or as a separate code file for each class (table).
- Base Class Output File: The name of the file that contains the Base classes. If you choose to output the Base classes as separate files, then supply the directory name here. This file will be overwritten each time you run the ClassBuilder to include any changes to the database. Because of this, you should never modify this file. Instead, you may extend the functionality of the Base class in its corresponding Child class.
- Create Child Classes: You may choose to output the Child classes as one single code file, or as a separate code file for each class (table).
- Child Class Output File: The name of the file that contains the Child classes. If you choose to output the Child classes as separate files, then supply the directory name here. If you have previoiusly added any code to the Child class, the ClassBuilder will not overwrite the Child class.
- SQL Output File: The name of the file that contains the SQL script to build the stored procedures for the classes. If you would like the ClassBuilder to automatically create the stored procedures, check the "Execute SQL" checkbox.
- Stored Proc. Prefix: You may choose to prepend the created stored procedures to help organize them in your database.
- Execute SQL: If you would like the ClassBuilder to automatically create the stored procedures, check the "Execute SQL" checkbox.
- Enums Output File: The name of the file that will contain the Enumerations build by the ClassBuilder. As an option, the ClassBuilder can create an enumeration using the values of a selected table. Tables are eligible for this if they two columns, the first being a numeric primary key and the second being a character-based value such as varchar. For example if you have a table called AddressType, the ClassBuilder can create an enumeration for this table that would look like this:
Home = 1
Office = 2
Other = 3
In your code, you could refer to these values by their name instead of having to remember their Integer values.
- Table Selection: The tables in your database will be listed in the grid. To build a Base and Child class for a table, check the "Build" column. To build an Enumeration for a table, check the "Lookup" column.
- Create Files (button): Click this button to save the ClassBuilder project and create your classes.
Inside the Base Classes
Overview
The Base classes contain the core functionality needed for data access.
One Base class is generated for each table in your database.
The Base classes are overwritten each time the ClassBuilder is run to incorporate any potential changes that may have been made
to the database schema. Because of this, you should never modify the Base classes. Instead, use the Child classes to extend any
functionality necessary for your project.
Fields
Each column in the table is represented as a Private field. Access to these are only obtained through their corresponding Public property.
There are several other “special” Fields that each class has. Each of them are access by Public properties:
IsLoaded(Boolean)
'This field keeps track of if the class has been successfully loaded from the database.
AttemptedLoad(Boolean)
'This field is set to true when the Load method is called, regardless of a successful load.
Properties
Each Field in the class is exposed through a Public property. The properties contain both Get and Set functionality. The Set function includes several features depending on the column data type. For character-based columns, the Set function will limit the length of the incoming value to match the length of the column specified in the database, preventing truncation.
There is also a private boolean field in each class called “IsDirty”. This field keeps track of any changes that might have been made to the class values. When the Set function is called, the incoming value is compared to the current value of the field. If they are different, the IsDirty flag is set to true. When called, the Update method checks this value and only performs the database update if IsDirty is true. This saves unnecessary trips to the database.
The following example is used for Objects and Collections
Let’s say you have a database that contains a Person and an Address table. The relationship is such that a Person can have many Address records. The Address table contains a PersonId column that is the foreign key to the Person table’s PersonId primary key.
Objects
For any column in the table that is the foreign key of another table, an Object is created. The Object is typed as the foreign key table object. Using the example above, the Address table would have an Object called “objPerson”. This would contain a reference to it’s parent Person record. If you have instantiated an Address object, you would be able to access the Person record information by saying:
txtFirstName.Text = Address.objPerson.FirstName
Collections
For any table that contains a foreign key to the current table, a Collection is created. Using the example above, the Person class would have a Collection called “colAddress”. If you have instantiated a Person object, you would be able to loop through each Address record of the Person object by saying:
For Each Address In Person.colAddress.Members
lstCity.Add(Address.City)
Next
Constructors
Two constructors are created for each class. The first is an empty constructor used for creating new records. Example:
Dim objPerson As New Person()
objPerson.FirstName = “Steve”
objPerson.LastName = “Sampson”
objPerson.Insert()
The second constructor requires a parameter that is the table’s primary key value. When this constructor is called, the Load method is automatically called, setting all of the class values. Example:
Dim objPerson As New Person(3341)
txtFirstName.Text = objPerson.FirstName
txtLastName.Text = objPerson.LastName
Methods
Load Method
This method runs the “select” stored procedure and sets the values of all of the fields. The AttemptedLoad field is set to true automatically, but the IsLoaded field is set to true only on a successful load from the database.
Insert Method
This method performs the “insert” procedure. On a successful insert, the primary key field will be updated with the newly assigned value, if Identity is turned on in the database.
Update Method
This method performs the “update” procedure only if the IsDirty field is set to true.
Delete Method
This method performs the “delete” procedure.
 
|
|
|