Getting started

Preface

Getting started with a complex system like an O/R mapper seems like a huge task: where to begin? how to do this and that with this system? LLBLGen Pro, although packed with features to make life easier, not harder, can still be a challenge at first: there is so many functionality, what to do best and so on and so on. This Getting Started section guides you in your initial steps towards a succesful usage of LLBLGen Pro.

How to begin? Read the Concepts section!

Firing up the GUI, creating a project, adding some entities, generating some code, it's not that hard to do, even without reading any documentation. The questions will start popping up when you want to use the code you just generated. It is essential when you start your journey into O/R mapping the LLBLGen Pro way, you click open the concepts section at the left and you read the Concepts section in full. Throughout the documentation, terms are used which are discussed in detail in the Concepts section and by having a good understanding of the meaning of these concepts, what the philosophy behind these concepts is and how they relate/interact with eachother in the LLBLGen Pro system, you'll find it easier to get started with the system, its generated code and its functionality.

"I've read the concepts, now what!?"

Ok, so you bit the bullet and read all the concepts? Good. Let's get started! First you have to setup your database schema properly. That is: create foreign key constraints, primary key constraints, unique constraints where appropriate, and normalize the tables as much as possible. If you want to get to know the functionality by using SqlServer's Northwind, that's fine too, as long as you can create a project from a solid database.

Setting up the GUI

First, it is important to set some preferences in the GUI. Open the preferences dialog by selecting File -> Preferences. See the section about the preferences: LLBLGen Pro designer, preferences and Project properties for more details about the various options you can set.

The second thing you probably want to setup is the singularization and pluralization in the designer. As not everyone uses the same language, we've refactored out the code to perform these conversions of names into two plug-ins. If you're using English names for the database elements of your database schema, it's wise to setup singularization and pluralization using the shipped plug-ins as these makes life easier for you when it comes to correcting names for entities and constructing names for fields mapped on relations and so on. It's easy to setup singularization and pluralization as described in the section LLBLGen Pro designer, Working with plug-ins - Designer events and plug-ins.

After you're done, it's time to create your first project.

Creating a new projects

Ok, let's create a project! To create a project, click on File -> New project (or press Ctrl-N). This will open the create new project dialog, as discussed in the LLBLGen Pro designer, creating a project section. See that section for details about creating a project.

Once the project is created you have a fairly empty project explorer and a catalog with one or more schemas in the catalog explorer. The next step is to verify the project properties are correct. Especially the MakeElementNamePascalCasing and the various strip patterns under Name construction can be of great use, as well as the FieldMappedOn* patterns. The project properties are inherited from the preferences set in the designer, and are stored in the project file so other developers in your team using the same project file will use the same project properties.

Adding entities

After you've created a new project (or loaded a clean project), it's time to add some entities! Click with your right mouse button on the 'Entities' node in the project explorer and select Add new entities mapped on tables from catalog(s)... option from the context menu (or select the Add new entities mapped on tables from catalog(s)... option from the Project menu). LLBLGen Pro will now determine which tables don't have a counterpart in the form of an entity definition in your project and will enlist all entities not yet added to your project in a dialog box, as shown in the section LLBLGen Pro designer, Adding entities. You can toggle the checkboxes of multiple entities by selecting one or more rows in the grid and by clicking Toggle checkboxes of selected rows. All entities with their checkbox checked are added to the project when you click 'Ok'.

Generating code

"That's it?" Well, to get started, yes. As LLBLGen Pro will determine all relations automatically, your project is already set up correctly with the relations present. Of course you're free to open entity editors of particular entities, rename fields mapped on table fields/relations, add custom properties, hide relations or create new relations if you haven't specified any foreign key constaints in the database. It's perhaps wise to examine the fields mapped on relations as LLBLGen Pro determines all possible relations for you and you probably want to give them proper names. You can do that in the project explorer by clicking with your right mouse button on a field or use the entity editor for that particular entity.

After you're satisfied with your project, press F7 or select Project -> Generate from the menu. This will open the generator configuration window. This window is discussed in detail in the LLBLGen Pro designer, generating code section. To get started, the SelfServicing template group is recommended, so select 'SelfServicing' on the first tab for Template group. Also select the right target platform you're going to use in your code, for example .NET 2.0. Then go to the third tab and select the preset you want to use, for example the TwoClasses preset. Select the language of choice (C# or VB.NET), specify the output directory and root namespace and click on Start generator. The output directory is the root of the files generated. It's wise to use a dedicated directory for the generated code.

"Cool, a lot of classes. And now I can query the database?"

Well, yes! To keep things simple, create a new VS.NET solution (or a multi-project project in the IDE you're using) and add the generated code project to that solution. The references to the runtime libraries should be OK. If you're using Oracle, perhaps the ODP.NET assembly Oracle.DataAccess.dll isn't referenced correctly and you should fix the reference. Either way, it's best to check if the VS.NET version you're using indeed loaded the correct assemblies, by clicking the LLBLGen Pro runtime libraries in the references listing and to see from which path they're loaded.

Add a new project to the solution, for example a console application. This is your .exe application which will be used to call into the generated code to work with the data. Now, drag the app.config file in the generated code project to the .exe project, which will now be able to use the connection string generated into the app.config file.

Add the ORM Support classes runtime library to the references of your .exe project: for VS.NET 2002, use the .NET 1.0 version, for VS.NET 2003 use the .NET 1.1, for VS.NET 2005 and VS.NET 2008 use the .NET 2.0 version. For CF.NET 1.0, use the CF10 version, for CF.NET 2.0 use the CF20 version and for CF.NET 3.5 use the CF35 version. Be sure you don't accidently reference the CF.NET version of the runtime library. For Linq usage, be sure the reference to the LinqSupportClasses is present in your project, as described in Compiling your code.

Of course, also reference the generated code project in your .exe project. Time to build the solution to see if everything is ok! This will build the generated code and the (still empty) .exe project. If your LLBLGen Pro project is very large (say, over 500 entities), compiling from VS.NET can be cumbersome (slow). It's recommended to use a build tool like Nant, MSBuild or command line tools to build the generated code in a separate solution.

If the generated code builds OK (in rare cases it can fail due to entity names conflicting with known classes. In this case: change the entity name in the GUI and regenerate the code), you're ready to get some data manipulation going!.

It's recommended that you start with the How Do I? section in the Tutorials documentation section: Tutorials and Examples, how do I ... ?. That section contains a lot of easy and advanced topics you will run into by using the generated code. Using the How Do I? section you can start without having to dig through the documentation about using entity classes and the like. Always keep in mind that the generated code is divided into namespaces, so you probably need to specify using/Imports statements at the top your file.

Also it's wise to do the tutorials listed in the Tutorials section.

After you get bored with the How Do I? and tutorials sections, you can start learning about the usage of the entity classes in code, by starting with LLBLGen Pro, using the generated code. and then selecting the section of the template group you chose when you specified the generator configuration. Also a good start are the example applications available on the LLBLGen Pro website.

Linq to LLBLGen Pro usage

If you want to use Linq to LLBLGen Pro in your project to query entities instead of the native LLBLGen Pro query API with predicates and the like, you could start right away with the Linq to LLBLGen Pro section. However you're adviced to also take a look at the Filtering and Sorting section of the template group you've chosen (Adapter, SelfServicing). This to give you a better picture what happens behind the scenes with a Linq query, and also gives you information what to do in the cases when a Linq query doesn't cut it (e.g. in edge cases with complex joins) and you have to fall back on the LLBLGen Pro query API.