Tutorial: Create an LLBLGen Pro project.

Preface

This tutorial guides you to the first steps of using LLBLGen Pro: the steps to create a new LLBLGen Pro project from an existing database schema. A similar (more limited) tutorial is also available in a Flash movie format on our website: Tutorial - Designer: Create a project (opens in new window)

Steps to create a project

Please follow the following steps to create a new LLBLGen Pro project from an existing database schema. SqlServer and 'Northwind' will be used as the targets, but you're free to select a different database type and database schema.

• Start the LLBLGen Pro designer. Either use the Programs start menu or double click the LLBLGenPro.exe in the installation folder to start the LLBLGen Pro designer.
• Select File -> New Project... or press Cntrl-N. The Create New Project dialog opens.
• Specify the name of the project, e.g. Northwind, and the name of the creator of the project, which is normally the user's name or the name of the organisation / deparment creating / owning the project. Check if the Location textbox indeed points to the folder you normally would want to save the project file to. If not, click the [...] button next to the Location textbox to select a different folder. The Database information area is now enabled.
• Select the database driver matching the database type to connect to. For this tutorial we'll connect to SqlServer and we therefore select the SQL Server 7/2000/2005 Driver (SqlClient). If you're following this tutorial to connect to Oracle using the MS Oracle provider driver, be sure to have an Oracle 8i or higher client installed. Each driver has its own Database connection information. The following steps are matching the SqlServer driver's Database connection information elements.
• Specify the server name. For servername, specify for example myserver.domain.com or if you're working locally on a SqlExpress installation, you probably need to use .\SQLEXPRESS
• Specify the authentication information. If you're working locally and you're running the designer as administrator, you could leave the Windows Authentication selected. If you want to connect to a remote server instance, it might be you need to specify a database account, e.g. sa and its password.
• Click Connect to connect to the specified server. The SqlServer driver will now obtain all catalogs (databases) in the SqlServer instance you connected to, to which the user you used to connect with as access.
• We're creating a project on Northwind, so we'll check the checkbox in front of Northwind in the list of Catalogs to use
• We'll fetch meta-data for tables, views and stored procedures, so we'll keep the checkboxes in front of Tables, Views and Stored procedures checked and click Create.
• LLBLGen Pro now knows enough information to obtain the meta-data for the project and will retrieve the meta data for the specified catalogs, in this case 'Northwind', from the database server and will create an empty project for you which will be shown in the Project Explorer.

You now have an empty LLBLGen Pro project. It's not really empty, it contains all the meta-data from the catalog(s) you specified, in this case Northwind, so you can design the entities without having to connect to the database server. If you open the Catalog Explorer (which is probably hidden away in a tab at the right edge of the LLBLGen Pro designer. Just click the tab to make it slide into view), you can browse through the meta-data just retrieved. When you click schemas, tables or their subnodes, a tab will open with the meta-information retrieved.

It's now time to do something useful with this meta data: map entities and other elements onto the tables and views!

Creating project elements

First we'll create some entities mapped onto the Northwind tables.

Mapping entities

• To create entities mapped onto tables, you can either Right-click Entities in the Project Explorer -> Add New Entities Mapped on Tables From Catalog(s) or you can select the main menu option Project -> Add New Entities Mapped on Tables From Catalog(s). You can also press Alt-E.
• The dialog to select which entities to create opens, showing all database tables in the catalog. As you can map as many entities onto a single target as you'd like, all tables are always listed. We don't have any entities in the project yet, so we'll simply check the checkbox at the top of the first column to check all checkboxes at once and click Add to project.
• In the Project Explorer, all entities you've added are now present. LLBLGen Pro automatically detected the relations between the entities you've specified (if there were any FK constraints defined in the database, and Northwind has these defined). All fields are mapped by default to a table field. Please click open some entity nodes to see that the entities indeed are filled with fields and relations.
• Save your work. It's now a good time to save the project. Click File -> Save Project to save the project to the Location specified when the project was created.
• To examine an entity in detail, Right-click the entity in the Project Explorer -> Edit / Properties. This will open the Entity Editor. You can also double-click the entity or press Cntrl-E while the entity is selected in the Project Explorer.

After we've mapped some entities, we'll now map a TypedView onto a database view, namely Invoices.

Mapping a typed view

• To map a TypedView onto a database view, either Right-click Typed Views in the Project Explorer -> Add New Typed Views From Catalog... or select Project -> Add New Typed Views From Catalog... The dialog we've already seen in step 1 when we're mapping entities pops up, however this time it shows the list of all views in the catalog(s) and already has pre-fabricated names for them. Check the checkbox in front of Invoices and click Add to project.
• In the Project Explorer the Invoices typed view has been added below the Typed Views node, including a field mapped onto each database view field. To see the TypedView in detail, right click it and select Edit / Properties or double click it.
• Save your project.

Mapping a stored procedure call

LLBLGen Pro also allows you to map methods to a stored procedure. In this tutorial we'll add a Retrieval Stored Procedure call to the SalesByYear stored procedure in Northwind

• Right click the Retrieval Stored Procedure Calls node below Stored Procedure Calls in the Project Explorer and select Add Stored Procedure Calls... or you could also use Project -> Add New Retrieval Stored Procedure Calls... The dialog with all the retrieval stored procedures found in the catalog(s) is shown
• In the list of stored procedures, check the checkbox in front of SalesByYear and click Add to project.
• Below Retrieval Stored Procedure Calls in the Project Explorer, LLBLGen Pro has added the stored procedure including its parameters and how many resultsets it will return.
• Save your project.

You've now created an LLBLGen Pro project which has entities mapped onto tables, a typed view mapped onto a database view and a stored procedure call mapped onto a stored procedure. In the following tutorials we'll use this project to create a small application which will show how to use the entities, the typed view and the stored procedure in your own code.