FastObjects .NET in Microsoft Visual Studio

Overview

The FastObjects Visual Studio .NET 2003 Integration offers an easy way to configure persistent properties and integrates seamlessly into the Visual Studio .NET build process. Currently, the following programming languages are supported: C#, J#, and Visual Basic.

Basics

The following guides you through the steps necessary to integrate FastObjects with your C# project. Building your project will then call the FastObjects .NET enhancer, converting your classes into persistence capable classes and automatically creating or updating a FastObjects dictionary (class schema) and database.

Specify the [FastObjects.Persistent] attribute for all classes that should be made persistence capable. The following example defines the Customer class as a FastObjects .NET persistence capable class.

using FastObjects;

[Persistent]
public class Customer
{
  // . . . 
}

Open the Project Properties window ( View | Properties Window). In the FastObjects section, type in the name of the database and the name of the schema to be created during the build process.

Also, set Enhancing to True so that the FastObjects .NET enhancer is called to create (or update) a dictionary and to register the persistence capable classes. The FastObjects .NET enhancer will also create a database if it does not exist.

Build the project. In a post-build step, the FastObjects .NET enhancer creates (or updates) the dictionary and database.

That’s basically it – now write your application code for reading and writing persistent objects!

Project Properties

The properties that can be defined for a FastObjects .NET project are given in the following list.

Database

This is optional and is the name of the database to be created when you build the project. It is recommended that you use a logical database name and map the logical database name to the physical database file name using a FastObjects configuration file (see below). If you are using the FastObjects SQL Object Factory, the database name field should be left empty. FastObjects databases and dictionaries (schema, see below) are discussed in the FastObjects .NET Programmer's Guide, chapter "The FastObjects Database".

Schema

This names the database schema (dictionary) to be created or updated when you build the project. It is recommended that you use a logical dictionary name and map the logical name to a physical file name using a FastObjects configuration file (see below). The dictionary name is written to the database header. Using a physical file name here will have the result that the database will always expect the dictionary to be in the file you specified. If a schema name is not specified then the classes are enhanced (assuming Enhancing is true) but not registered in the dictionary.

ConfigFile

Specifies the absolute path and filename of the FastObjects configuration file you wish to use for the project. In the configuration file the logical database and schema name can be mapped to physical names, for example.
For more information about FastObjects configuration files, refer to the the FastObjects Configuration Guide. You can find it in the doc directory where you installed FastObjects .NET.

Enhancing

If the value for is set to true, the FastObjects .NET enhancer, ptil, is called automatically after the Visual Studio .NET compiler has finishing. The FastObjects .NET enhancer modifies the project assembly to enable transparent loading and storing of member values of persistent instances and registers all persistent classes in the dictionary. If the project contains persistent classes, Enhancing should be set to true. If set to false, the FastObjects .NET enhancer is not called.
The FastObjects .NET enhancer is described in the FastObjects .NET Programmer's Guide chapter "The FastObjects .NET Enhancer".

Output and Task List Window

Any warnings and errors that the FastObjects .NET enhancer produces are reported to the Output window and to the Task List in Visual Studio. The FastObjects .NET enhancer runs only if the .NET compiler completes without errors.

The Output window

All FastObjects warnings and errors are reported to the Output window (in the Build pane). If the Enhancing project property for the project is true, the following output appears in the Build pane for a successful FastObjects .NET build.

FastObjects enhancing...  FastObjects
enhancing complete -- 0 errors, 0 warnings

The following shows an example display of a FastObjects .NET error.

FastObjects
enhancing...  c:\grandunifiedexample\01_storingobjects\customer.cs(11):  
 Backend registration: Index 'nameIdx' uses non-existing fields of class
'BusinessObjects.Customer': lastname [class=BusinessObjects.Customer] [index=nameIdx]
 FastObjects enhancing complete -- 1 errors, 0 warnings

A double-click on the error positions the cursor on the corresponding class definition.
A solution build displays the following output.

FastObjects
All: 1 succeeded, 0 failed, 0 skipped

The number of skipped FastObjects .NET projects is the number of projects where the Enhancing project property is set to false.

The Task List

All FastObjects .NET warnings and errors are reported to the Task List. The are categorized under the task Build Errors which is the default task in Visual Studio .NET and displayed when any compile errors occur. They are also visible in the All category. In order to distinguish .NET compiler errors from FastObjects .NET enhancer errors, all FastObjects .NET enhancer errors are displayed with the prefix "FastObjects". Double-clicking on a FastObjects .NET enhancer error or warning displays the corresponding source file with the cursor positioned to the beginning of the class definition (this might not be on the exact line where the error occurred). The error description gives detailed information about the position and the reason for the error.

Menu Commands

The FastObjects .NET menu command bar provides commands for creating and updating a database.

Create Database
Creates a new database according to the database name, schema name and config file defined in the project properties.

Update Database
Updates an existing database according to the database name defined in the project properties.

The commands do only work if the project or project item files are selected in the Solution Explorer or in the Class view. Both commands can also be executed in the Command View of Visual Studio .NET.

Typing FastObjects lists all commands which are currently available, i.e.

FastObjects.DataBaseCreate and FastObjects.DatabaseUpdate

Cross-project Development

The FastObjects Visual Studio .NET integration transparently supports cross-assembly development of assemblies with persistent classes. You can, for example:

• Derive a class from a class which is defined in another assembly.
  
• Define a member in a class which is defined in another assembly.
  

For cross-project assembly references, the referenced assembly must be added to the project references.

A solution might consist of multiple library and application projects. For configuring the FastObjects .NET project properties, you should keep in mind the following interdependencies between projects:

• If a schema name in one project is not specified, then the classes are enhanced (assuming the Enhancing property is set to true) but not registered in the dictionary.
• Referenced assemblies with persistent classes must already be enhanced. If they are not yet registered in the dictionary, they will be registered in the schema of the referencing project.
  
• It is possible to specify the same database, schema and configuration file names in multiple projects.
  

If the solution consists one application that references multiple libraries with persistent classes, the following project property configurations are possible.

Configuration 1

For libraries with persistent classes: Enhancing set to true and the schema and database names not specified.
For the application that references the libraries: Enhancing set to true and the schema and database names are specified (this will register all classes in the dictionary and creates or update the database).

Configuration 2

For libraries with persistent classes: Enhancing set to true and the schema and database names specified. This creates or updates the dictionary for every build.
For the application referencing the libraries (with persistent classes): Enhancing set to true and the same schema and database names as in the libraries are specified to update the dictionary and database. If the application has no persistent classes, Enhancing can be set to false and schema name left empty.

Troubleshooting

The FastObjects Visual Studio .NET Integration is implemented as an Add-in to Visual Studio .NET. If the menu of the FastObjects .NET Add-in does not appear in the main menu bar, check if the FastObjects .NET Add-in is activated in the Visual Studio .NET Add-in Manager (Tools | Add-in Manager). The FastObjects .NET Add-in should be selected in the columns Available Add-ins and Startup. You can also check that registry key

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\7.1\AddIns\FastObjects

value for LoadBehavior is greater than zero. Also, make sure that the library FastObjects.t7.SDK.Addin exists in the bin directory of your FastObjects .NET installation. If everything seems to be correct and the FastObjects .NET Add-in still does not appear, you should re-install FastObjects .NET.