📄 help.htm
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
<HTML>
<HEAD>
<TITLE>LLBLGen documentation</TITLE>
<style type="text/css"> <!-- BODY,TD { font-family : Arial, Helvetica, sans-serif, Verdana, Geneva; font-size : 10pt; color : #000000; }
H1 { font-size : 13pt; color : #006486; }
H2 { font-size : 11pt; font-weight : bold; }
-->
</style>
</HEAD>
<BODY bgcolor="#ffffff" text="#000000">
<h1>LLBLGen Documentation</h1>
<b>Documentation for 1.1</b>
<h2>What's it for?</h2>
<p>
LLBLGen generates all code for a complete data-tier for the given database. The data-tier generated
consists of two parts: a file with all SQLServer stored procedures and a directory with C# classes.
The C# classes can be compiled to a DLL / .NET assembly and is then ready to be used in other applications.
The SQLServer stored procedures, generated as one T-SQL script, are ready to be added to the given database.
By using LLBLGen, the developer can save a lot of development time by simply generating the complete
data-tier using LLBLGen and using the output instead of writing the data-tier by hand.
</p>
<P>Developers should first model their database inside SQLServer, including
foreign key constraints and all necessary tables. Only in that situation LLBLGen
is able to produce the right code for the developer. After the developer has
generated the data-access code using LLBLGen and has compiled the assembly,
development of the business logic layer(s) can start. </P>
<h2>Prerequisits and targetplatform specs.</h2>
<p>
LLBLGen is an application written in C# and therefor
needs the .NET platform v1.0 or higher to run. LLBLGen is a tool targetting
SQLServer 7.0 or higher
specifically and can't be used on other databases from other vendors, like Oracle, or on other types of
databases, like MS Access. LLBLGen does work with MSDE v7.0 or higher, since MSDE is SQLServer 7.0
or higher compatible. LLBLGen can generate COM+ compatible C# classes, and these will only run on COM+ compatible
systems, which are Windows 2000 versions and Windows XP versions or higher.
</p>
<p>
To compile the outputted C# classes, the
developer needs the .NET SDK v1.0 or higher, or compatible C# compiler (f.e. Rotor) and available .NET Library
with System.Data.* namespaces. To run the generated T-SQL script with the SQLServer stored procedures, the
developer needs isql.exe or other T-SQL executing client, f.e. Query Analyzer. These tools come with
SQLServer or MSDE.
</p>
<p>
LLBLGen uses a SQLServer 7.0 or higher database as
input. The database doesn't have to be filled. To fully
use the potential of LLBLGen, foreign key constraints should be present when LLBLGen is ran. LLBLGen doesn't store any
code nor data in the database nor does it modify the structure of the database.
</p>
<h2>Design philosophy of the code generated.</h2>
<p> LLBLGen generates code, and generated code is almost never truly the same as handwritten code, its style,
format, even general structure, can be different than the way the developer usually writes code. Using the
GUI, the user can 'tune' the way LLBLGen generates code, but there are things you can't tune with the GUI but can
be odd at first.
</p>
<p>
The
main design philosophy of LLBLGen was that the generated code should be as close to handwritten code as possible
and should be extensible. This way, LLBLGen generates comments where comments are needed, uses properties
for input of data and tries to layout the code as clean as possible. LLBLGen will use #regions to mark
areas in the generated C# code (f.e. the member declarations and the property declarations) so that users of
Visual Studio.NET can collapse these areas. All generated code is modelled
after real life hand written production code and best practices experiences. When you still find the code looks
awful you can grab the sourcecode of LLBLGen and manually adjust the way the output is generated. The sourcecode
is extensively commented so diving into it shouldn't be a big nightmare.
<br><br>
<b>C# base class.</b><br>
LLBLGen generated code uses an abstract base class
for
all the C# classes. This class contains the connection object needed for each C# class and a property
which will reflect the @@ERROR T-SQL variable, if the user selected generation of that code. Also this abstract base
class is created with extensibility in mind, so developers can add code which is common for all C# classes to
this base class without any hassle with the other generated code. This abstract base class, when selected,
<br><br>
<b>app.config</b><br>
LLBLGen also generates an app.config file which should be added to every project the compiled assembly of the generated
C# classes is added to. The app.config file will contain the connection string definition for the database.
The base class will read this connection string, so all generated classes will automatically use the same
connection string, which is easily adjustable by editing the app.config file.
<br><br>
<b>One property for each tablefield</b><br>
LLBLGen generates for each table found in the database given one C# class. For each field that is not excluded
(see below) a property is generated too. These properties are get/set properties and should be used by a calling
class to set values before a method is called and should be used to retrieve new Identity values after an insert
method call. Which property to set for each call is generated in /// comments above each C# method, when C# comment
generation is selected.
</p>
<h2>How to use LLBLGen.</h2>
<p>
Starting LLBLGen will first result in a small window which requests the database server and catalog (database)
information plus the security connection parameters. Pressing OK will result in the opening of the main window.
</p>
<p>
The main window is divided in several parts: the Code Generation Parameters section, the Progress section and
at the bottom the action buttons and the status bar showing which server and catalog is currently selected.
LLBLGen presets the controls so it's ready to roll, but some occasions require changing some configuration
parameters. Below are the configuration parameters described per section.
</p>
<p>
<b>C# Classes configuration parameters</b>
<ul>
<li><b>Namespace</b>. This is the name for the namespace which will be generated into the C# classes LLBLGen
will produce. As a default, LLBLGen takes the catalog name and adds 'LLBL' to it. Select this name with care,
since it will be the name you also will use in every application which will use the compiled C# classes.
<li><b>Include comments</b>. If you
want comments generated into the C# classes, like the /// <summary>
comments and other useful comments, select this box. It's selected by default.
<li><b>Prefix Variables (HC)</b>. All C# classes have properties for the data stored into the tables and passed
to the stored procedures. If you want these properties have Hungarian Coding style prefixes, like 'i' for
int properties, check this box. LLBLGen will also prefix the membervariables with the same prefix then.
Membervariables are always prefixed with 'm_'. </li>
</ul>
<b>T-SQL Stored Procedures configuration parameters</b>
<ul>
<li><b>Include iErrorCode</b>. If
you want extra error reporting in both the C# classes and the stored
procedures, check this box. LLBLGen will then generate extra T-SQL code so the
@@ERROR value will be reported back to the calling C# method in the variable
@ErrorCode, if prefixing is switch off or @iErrorCode if prefixing is switched
on.
<li><b>Prefix Params</b>. This is
the equivalent of Prefix Variables (HC) in the C# section for the T-SQL code.
<li><b>Include drops</b>. When
selected, LLBLGen will generate code to first drop an already existing version
of the stored procedure before the create code is executed. With a database
with a lot of tables, it can be wise to switch this box of, if you're running
the script on an empty database.
<li><b>Include comments</b>. Check
this box if you want comments in your stored procedure code. LLBLGen generates
extensive comments for Stored Procedures to ease development of the T-SQL
code.
<li><b>Generate Delete Triggers</b>.
Not Yet Implemented (tm)
<li><b>Generate Select SPs</b>.
Checking this box will make LLBLGen generate for each table one select stored
procedure, plus the corresponding C# method, which will select one row from
the table based on the Primary Key. When foreign key constraints are present
in the database, LLBLGen will also generate for each table for each foreign
key in that table one selectall stored procedure, plus the corresponding C#
method, which will select all rows from that table based on that foreign key
field.
<li><b>Generate Update SPs</b>.
Checking this box will make LLBLGen generate for each table one update stored
procedure, plus the corresponding C# method, which will update one existing
row in that table based on the Primary Key. LLBLGen will not generate stored
procedures which will update only Primary Key fields.
<li><b>Generate Delete SPs</b>.
Checking this box will make LLBLGen generate for each table one delete stored
procedure, plus the corresponding C# method, which will delete one existing
row from that table based on the Primary Key. LLBLGen will not generate delete
stored procedures for foreign keys in a table, this should be done by
triggers, which will be generated by LLBLGen in a later version. (hence the
not yet implemented Generate Delete Triggers feature :) )
<li><b>Generate Insert SPs</b>.
Checking this box will make LLBLGen generate for each table one insert stored
procedure, plus the corresponding C# method, which will insert one new row in
that table. Identity fields are supported and returned in properties.
<li><b>Generate SelectAll SPs</b>.
Checking this box will make LLBLGen generate for each table one select stored
procedure which will simply select all rows from that table, ordered by the
Primary Key, ascending.
<li><b>SP Prefix</b>. This is the
prefix that is used to generate the name of the stored procedure. The name of
a stored procedure is generated as follows: SP Prefix + Table name + _ +
Action (insert, delete etc).
<li><b>Excluded fields in update/insert queries</b>. Per line you can specify fieldnames which shouldn't be
used in update and insert queries. This means that the values for these fields are not passed to the
stored procedures by the C# methods but are generated in the T-SQL code. A good example is a timestamp
field in each table which reflects the date/time the record is created. Excluding that field results in
T-SQL Code which will insert a default value into that field when a row is updated or inserted. For
string types, this is an empty string, for date/time fields this is the result of GETDATE(), for
numeric fields this is 0.</li>
</ul>
All methods will throw exceptions when an error occurs, all select methods will return a DataTable object with
the results gathered. When generated, the ErrorCode property will reflect the value of @@ERROR after the T-SQL
statement was executed. When an insert method was called on a table with an Identity column, the property corresponding
with that field holds the new value after the insert completed, unless an exception was thrown.
<br><br>
<b>Output paths</b>
<ul>
<li><b>C# classes output path</b>.
Specify the path where LLBLGen will store the generated C# class files. If the
directory is not found, it will be created. All classes are overwritten by
default. The names for the C# classes are generated as follows: 'cls' + Table
name + '.cs'.
<li><b>T-SQL output path</b>. Specify the path where LLBLGen will store the T-SQL script with the
stored procedures. If the directory isn't present, it will be created. The name of the T-SQL output
file is generated as follows: Catalogname + '_LLBL_storedprocedures.sql'. If a file with that name
is already present it is overwritten.</li>
</ul>
<P></P>
<p>
To start LLBLGen, you simply press the Start button. LLBLGen will check the filled in credentials for the
database and will then start processing. The Progress section is now enabled and essential feedback is given
in the textarea plus via the progress bar. LLBLGen is finished when the Code generation parameters section is
re-enabled again.
</p>
<h2>Compiling the C# classes and use the assembly.</h2>
<p>
LLBLGen generates besides the C# classes two extra files: app.config and clsDBInteractionBase.cs. The
file app.config is used to store the connection string and should be added to <i>every</i> project the
compiled assembly is referenced by. This way you can control to which database the compiled assembly will
connect to by simply editing this file. The file clsDBInteractionBase.cs is the base class all generated
C# classes inherit from. It contains the connection object construction and maintenance and, if generated,
the handling for the ErrorCode property which reflects the value of @@ERROR.
</p>
<p>
Compiling the .cs classes is easy. Open a dosbox and run vsvars32.bat. This will add path settings and
environment variables necessary for the .NET SDK commandline tools. After that, run:
<code>
<pre>
csc /out:<i>mydllname</i>.dll /target:library /optimize *.cs
</pre>
</code>
This will result in a dll, <i>mydllname</i>.dll, which contains the assembly for the
generated code. Applications can now reference to this assembly and create
objects using the generated classes to interact with the database used to
generate the code.
<P></P>
<h2>Known issues.</h2>
<p>
<ul>
<li>LLBLGen uses a query to retrieve field- and table
information from the database specified. Allthough no system specific tables
are used, the user specified to connect to the given server can be unable to
retrieve essential info due to accountrestrictions. If LLBLGen fails due to
these restrictions, the user hasn't an option to re-specify the credentials
but has to restart the tool.
<li>The query used by LLBLGen is long and uses several subqueries. Due to a limit in MSDE (5 concurrent transactions
will run, any other has to wait) the query is slow and CPU intensive. On a normal SQLServer installation
however it's very fast. The generation of all the code for a database with 30 tables and foreign key constraints
takes on a normal SQLServer 2000 server installation on a dual P3-933 about 2 seconds, on a MSDE2000
installation on a P3-933, about 45 seconds.</li>
</ul>
<P></P>
</BODY>
</HTML>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -