This document provides a summary of how to use dOOdads, a .NET object-relational mapping tool, to perform common data access tasks. It discusses database and project preparation, generating dOOdads classes from an existing database using MyGeneration templates, setting the connection string, and performing basic CRUD operations. It also covers more advanced features like dynamic queries, data binding, special functions, and the object model.
This document provides a summary of how to use dOOdads, a .NET object-relational mapping tool, to perform common data access tasks. It discusses database and project preparation, generating dOOdads classes from an existing database using MyGeneration templates, setting the connection string, and performing basic CRUD operations. It also covers more advanced features like dynamic queries, data binding, special functions, and the object model.
This document provides a summary of how to use dOOdads, a .NET object-relational mapping tool, to perform common data access tasks. It discusses database and project preparation, generating dOOdads classes from an existing database using MyGeneration templates, setting the connection string, and performing basic CRUD operations. It also covers more advanced features like dynamic queries, data binding, special functions, and the object model.
Ported to C# by David Neal Parsons TABLE OF CONTENTS
Preparation Database Design Tips 2 Installation and Setup 2 CRUD procedures 3 dOOdads for tables 3 dOOdads for views 3 Concrete classes 3 ConnectionString 4 Enhancing concrete classes 4
Common tasks Retrieve all rows 5 Retrieve one row by primary key 5 Retrieve one or more rows based on other criteria 5 Insert row 5 Delete row 5 Update row 5 Get number of rows 5 Iterate through rows 5 Set the sort expression 6 Set the filter expression 6 Calculated columns 6 Set ConnectionString explicitly 6 Set the current row 6 String properties 6
DynamicQuery WhereParameter enums 8 Retrieve rows 8 Limit columns returned 9 Order By 9 Select Distinct 9 Select Top N 9 Parentheses 9 GenerateSQL 9 ReturnReader 9
Data binding Datagrid 10 ComboBox 10 DropdownList 10
Special functions LoadFromSql* 11 FromXml/ToXml 12
TransactionMgr 13
Object model 14 MyGeneration dOOdads C# Quick Reference Steve Corn Page 2 of 14 6/27/2005 Ported to C# by David Neal Parsons PREPARATION
Database Design Tips (MS SQL Server) TOC 1. For each table, use a single identity column as the primary key. 2. For each table, add a column named "RowVersion" with a datatype of timestamp. (dOOdads will use this column to handle concurrency.) 3. Since dOOdads doesn't handle joins, prepare the joins ahead of time by creating views. 4. Wherever possible, design your database and application to minimize problems with nulls. When you do run into problems with nulls, see String Properties.
Install MyGeneration and add the dOOdads project to your solution TOC 1. Download from http://www.mygenerationsoftware.com and install. 2. The installer puts the application in Program Files. 3. Add the dOOdads project to your Visual Studio solution: a. Right-click on the Solution item and choose "Add Existing Project". b. Navigate to the dOOdads project (C:\Program Files\MyGeneration\ Architectures\dOOdads\CSharp\MyGeneration.dOOdads\ dOOdads.csproj) and select. The dOOdads project will now appear in your solution. c. In the DbAdapters folder, open the "Entity" corresponding to your database (e.g. SqlClientEntity). Find "Build Action" in "Properties" and set to "Compile". Repeat for the "DynamicQuery" adapter. 4. Build the dOOdads project.
Get your .Net project ready for dOOdads 1. Add a reference to the dOOdads assembly to your project: a. Right-click on "References" and choose "Add Reference". b. On the Projects tab, double-click on the dOOdads project and click "OK". 2. Add 2 folders to the project: a. DAL (data access layer) - to hold the abstract classes created by MyGeneration b. BLL (business logic layer) - to hold the concrete classes that inherit the abstract classes
MyGeneration dOOdads C# Quick Reference Steve Corn Page 3 of 14 6/27/2005 Ported to C# by David Neal Parsons With MyGeneration:
Create the CRUD stored procedures TOC Start MyGeneration. 1. Edit | DefaultSettings and set the database. 2. Select the template that will generate stored procedures that will work with dOOdads (e.g., "SQL Stored Procedures"). 3. Run the template, select the tables you want (usually all of them), and click OK. 4. The generated DDL will be copied to the Clipboard and displayed in the Output page. 5. Go to the query tool for your database, paste the DDL code, and execute to create the stored procedures.
Create the dOOdads for tables TOC 1. Return to MyGeneration and select the template that will generate the dOOdads code for tables (eg, "dOOdads Business Entity"). 2. Run the template, change the output path to the DAL folder in your project, select the tables you want (usually all), and execute to create the abstract classes. 3. The class name for each of these dOOdads will start with an underscore.
Create the dOOdads for views TOC 1. Select the template that will generate the dOOdads code for views (e.g., "dOOdads Business View"). 2. Run the template, change the output path to the BLL folder in your project, select the views you want (usually all), and execute to create the concrete classes. 3. The class name for each of these dOOdads will NOT start with an underscore because they are already concrete classes in the BLL folder.
Write the concrete classes corresponding to the abstract classes TOC 1. Run the Concrete Classes template, saving the code in the BLL folder of your project 2. or write the classes yourself as follows:
public class Employees : _Employees { public Employees() {
} } MyGeneration dOOdads C# Quick Reference Steve Corn Page 4 of 14 6/27/2005 Ported to C# by David Neal Parsons With Visual Studio:
Include the dOOdads in your project 1. Right-click on the DAL folder and select Include in project. 2. Repeat for the BLL folder.
Enter the connection string in the AppSettings section of the config file TOC 1. Put the connection string in the web.config (for web apps) or app.config (for WinForms apps) file and name it "dbConnection". 2. If the connection string is not explicitly assigned in the dOOdad, the dOOdad will look in the config file for "dbConnection".
Enhance your concrete classes TOC If you wish to add any custom properties and methods to your business entities, you can do so in the concrete classes at any time. If your data structure changes and you need to recreate your dOOdads, the code you add here will not be overwritten.
For processing related to the business entity that normal dOOdads methods won't handle, consider using the special LoadFromSql* methods (see SPECIAL FUNCTIONS) here in the concrete class. MyGeneration dOOdads C# Quick Reference Steve Corn Page 5 of 14 6/27/2005 Ported to C# by David Neal Parsons COMMON TASKS Prep Employees emps = new Employees(); int empID;
Retrieve all rows TOC emps.LoadAll();
Retrieve one row by primary key TOC emps.LoadByPrimaryKey(empID);
Retrieve one or more rows based on other criteria TOC See DYNAMIC QUERY
Insert row TOC emps.AddNew(); emps.LastName = "Smith"; emps.HireDate = DateTime.Now; emps.Save(); empID = emps.EmployeeID; //emps returns new key value
Delete row (also see SET THE CURRENT ROW) TOC //already have the desired row set as the current row, then... emps.MarkAsDeleted(); emps.Save();
Update row (also see SET THE CURRENT ROW) TOC //already have the desired row set as the current row, then... emps.LastName = "Jones"; emps.Save();
Get number of rows TOC emps.RowCount;
Iterate through rows TOC if(emps.RowCount > 0) { emps.Rewind(); //move to first record do { //do something with the current row } while(emps.MoveNext()); }
MyGeneration dOOdads C# Quick Reference Steve Corn Page 6 of 14 6/27/2005 Ported to C# by David Neal Parsons Set the sort expression TOC emps.Sort = Employees.ColumnNames.LastName + " DESC";
Set the filter expression TOC emps.Filter = Employees.ColumnNames.LastName + " LIKE A%";
Calculated columns (used by your application in the dataset, but not stored in the database) TOC AddColumn SetColumn GetColumn IsColumnNull SetColumnNull
ConnectionString TOC Define the connection string in your config file, naming it "dbConnection". If you choose not to do that or you are using more than one database, you can use the ConnectionString property of the dOOdad. emps.ConnectionString = "User=me;Password=pw;Database=Employees;DataSource=MyServer"
Set the current row TOC Before you can change values in a row or delete a row, the row to change must be assigned to the DataRow property (the current row). This is accomplished in several ways: 1. LoadAll or Query.Load the current row is the first row 2. LoadByPrimaryKey the current row is the returned row 3. AddNew the current row is the new row before it is inserted into the database 4. Rewind and MoveNext Rewind sets the current row to the first row in the existing DataTable; MoveNext sets the current row to the row it moves to.
String properties TOC Another very handy feature of dOOdads is called string properties. This simplifies the handling of null values in both string and non-string columns. For each data column in the dOOdad, there is a string property in addition to the column property. MyGeneration dOOdads C# Quick Reference Steve Corn Page 7 of 14 6/27/2005 Ported to C# by David Neal Parsons For example: emps.Salary and emps.s_Salary emps.HireDate and emps.s_HireDate
Check if a value is null: if(emps.s_Salary == "") if(emps.s_HireDate == "")
Set a value to null: emps.s_LastName = ""; emps.s_HireDate = "";
MyGeneration dOOdads C# Quick Reference Steve Corn Page 8 of 14 6/27/2005 Ported to C# by David Neal Parsons DYNAMIC QUERY
The dynamic query property of the dOOdad (MyDoodad.Query) allows you to select records in an ad hoc fashion without having to write a bunch of little stored procedures. (And its design precludes the possibility of SQL-injection attacks.)
WhereParameter enums (see object model diagram for C#) TOC
Conjunctions (WhereParameter.Conj) And Or UseDefault
Directions (WhereParameter.Dir) ASC DESC
Operands (WhereParameter.Operand) Between Equal GreaterThan GreaterThanOrEqual In IsNotNull IsNull LessThan LessThanOrEqual Like NotEqual NotIn NotLike
MyGeneration dOOdads C# Quick Reference Steve Corn Page 9 of 14 6/27/2005 Ported to C# by David Neal Parsons Limit columns returned (Save() cannot be called after limiting columns.) TOC emps.Query.AddResultColumn(Employees.ColumnNames.EmployeeID); emps.Query.AddResultColumn(Employees.ColumnNames.LastName); emps.Query.Load();
Order By TOC emps.Query.AddOrderBy(Employees.ColumnNames.HireDate, WhereParameter.Dir.DESC);
GenerateSQL TOC A diagnostic function that returns the SQL statement created for the dynamic query. After calling this you cannot load the object. Better to use LastQuery.
LastQuery TOC A string property that contains the SQL text of the most recently generated SQL statement.
ReturnReader TOC SqlDataReader reader = emps.Query.ReturnReader() as SqlDataReader; MyGeneration dOOdads C# Quick Reference Steve Corn Page 10 of 14 6/27/2005 Ported to C# by David Neal Parsons DATA BINDING
Data binding to a datagrid (Web app) TOC 1. Create a typed Dataset (.xsd file) with a DataTable to match the dOOdad columns. 2. Add the Dataset to your form. 3. Add a DataView and assign the new Dataset.DataTable to its Table property. 4. Bind the datagrid to the DataView and design the DataGrid as you wish. 5. In the code-behind, change the DataView's Table property to the DefaultView property of the dOOdad: if(emps.LoadAll()) { dvEmps = emps.DefaultView; dgEmps.DataSource = dvEmps; dgEmps.DataBind(); } (NOTE: The only reason to use a dataset here is to help design the datagrid visually at design time. The dataset is not referenced in code at all.) 6. If you wish, you can store the dataview in the Session as follows: Session["dvEmps"] = emps.DefaultView; dvEmps = Session["dvEmps"];
Data binding to a ComboBox (WinForms app) TOC //get data emps.Query.AddResultColumn(Employees.ColumnNames.EmployeeID); emps.Query.AddResultColumn(Employees.ColumnNames.LastName); emps.Query.AddOrderBy(Employees.ColumnNames.LastName, WhereParameter.Dir.ASC); emps.Query.Load();
Data binding to a DropDownList (Web app) TOC //get data emps.Query.AddResultColumn(Employees.ColumnNames.EmployeeID); emps.Query.AddResultColumn(Employees.ColumnNames.LastName); emps.Query.AddOrderBy(Employees.ColumnNames.LastName, WhereParameter.Dir.ASC); emps.Query.Load();
//bind to drop-down list ddlEmployees.Datasource = emps.DefaultView; ddlEmployees.DataTextField = Employees.ColumnNames.LastName; ddlEmployees.DataValueField = Employees.ColumnNames.EmployeeID; ddlEmployees.Databind(); MyGeneration dOOdads C# Quick Reference Steve Corn Page 11 of 14 6/27/2005 Ported to C# by David Neal Parsons SPECIAL FUNCTIONS
Executing custom stored procedures and SQL statements: TOC Method Name Overloads Returns Fills dOOdad LoadFromSql (s) (s, p) L (s, p, c) L Boolean (true if any rows are found) Yes LoadFromSqlNoExec (s) (s, p) L (s, p, c, t) L Integer (number of rows affected) No LoadFromSqlReader (s) (s, p) L (s, p, c) L DataReader No LoadFromSqlScalar (s) (s, p) L (s, p, c, t) L Object (first column of first row in resultset) No LoadFromRawSql (s, p) P Boolean (true if any rows are found) Yes s : stored procedure (or SQL statement depending on command type) p : parameters (ListDictionary L or ParamArray P ) c : CommandType (sproc, table, SQL statement) t : timeout (-1 is standard)
These functions can be used to extend the concrete class (in fact, they cannot be accessed outside of the concrete class). See the examples on the next page.
MyGeneration dOOdads C# Quick Reference Steve Corn Page 12 of 14 6/27/2005 Ported to C# by David Neal Parsons
LoadFromRawSql this.LoadFromRawSql("SELECT MIN(EM_HireDate) FROM tEmployees WHERE EM_Active = {0}","1");
FromXml / ToXml TOC emps.Query.Load(); //emps.RowCount = 200 emps.LastName = "Griffinski"; //Change first row emps.GetChanges(); //emps.RowCount now = 1 string xml = emps.ToXml();
//Now reload that single record into a new Employees object and save it Employees empsClone = new Employees(); empsClone.FromXml(xml); empsClone.Save();
MyGeneration dOOdads C# Quick Reference Steve Corn Page 13 of 14 6/27/2005 Ported to C# by David Neal Parsons TOC TRANSACTIONMGR