Generated code - Application configuration through .config files

Preface

The generated code, both adapter and selfservicing, offer a couple of application-wide configuration settings which can be added to the .config file of your application (be it the app.config file for a .exe application or the web.config file for a service/webapplication). Besides the settings for the connection string (see Compiling the code) and trace listener setup (see Troubleshooting and debugging), you can configure several core elements of how the generated code will behave.

Several of these elements have been described elsewhere in the manual as well. They're listed here for clarity so you have a single section to find all config file settings for an LLBLGen Pro application. When mentioned here, we've added a link to their actual documentation so you will see their documentation in context.

Dependency Injection settings

Dependency injection auto-discovery is switched off by default. To enable it, add a setting to the .config file. See: Setting up and using Dependency Injection - Auto-discovery of instance types

To manually specify which assemblies the LLBLGen Pro runtime framework should discover for injectable types, you've to add a section to the .config file. See: Setting up and using Dependency Injection - Manual discovery through dependencyInjectionInformation sections in the .config file

Trace switch settings

To setup tracing in LLBLGen Pro, you've to add a section of switch elements to the .config file. See Troubleshooting and debugging - Conventions.

Culture specific format specifications

To specify the culture to use for serializing and deserializing System.Single, System.Double and System.Decimal typed values to and from XML, you should add the following element to the appSettings element of the config file of the applications which serialize and deserialize XML data, where name of culture is replaced with either nothing (so value is empty, for the invariant culture) or the name of the culture to use, e.g. nl-NL or en-US. For the full list of iso culture names please see the CultureInfo class documentation in the MSDN.

<add key="cultureNameForXmlValueConversion" value="name of culture" />

Entity behavior settings

To automatically mark a saved entity as 'Fetched', add a setting to the .config file. See Using the entity classes - Setting the EntityState to Fetched automatically after a save: for adapter and for selfservicing.

To bypass build-in validation logic in favor for your own validation logic, add a line to the config file settings. See: Validation per field or per entity - Bypassing build-in validation logic

To define the correction action for a Scale overflow error, add a line to the config file settings. See: Validation per field or per entity - Defining the Scale overflow correction action to use

To specify that the LLBLGen Pro runtime should use case insensitive hashcodes for strings (the hashcode for "Foo" is the same as for "FoO"), the following key should be added to the appSettings element of the config file of the application:

<add key="caseSensitiveStringHashCodes" value="false" />

By default, hashcodes are case sensitive, omitting this setting or setting it to true in the config file results in the default behavior. Hashcodes for string values in entity fields are used in prefetch path mergers and for example projection distinct filtering. In general you should keep this setting set to the default (true). Only set this to false if you're working with a case-insensitive database which has FK values which differ only in casing from their PK counterparts (e.g. the FK field value is "Foo" and the PK field value is "foo"

Catalog name overwriting (SqlServer, Sybase ASE)

For generated code targeting SqlServer or Sybase ASE, it can sometimes be necessary to use the generated code with a catalog with a different name than the catalog the project was created with. As LLBLGen Pro generates the catalog name into the code, it might be necessary to specify a way to rename the catalog name in the generated code at runtime with a given name. LLBLGen Pro supports multiple catalogs per project, so you can specify more than one rename definition. This feature is similar to the feature discussed in Using the generated code / Adapter / DataAccessAdapter functionality (multi name setting) as it also offers a way to rename multiple catalogs in one go. The renamed data is stored in static hashtables which assure that the Dynamic Query Engines (DQE) for SqlServer and Sybase ASE use the right catalog names without losing any performance.

To setup the renaming of catalogs, follow these steps. The first tag in the configuration tag in the .config file has to be the configSections tag. In there, place a section definition tag as shown in the example below:


Then, the catalog name overwrite definitions have to be placed in key/value pairs inside the sqlServerCatalogNameOverwrites tag, similar as the following examples. The sqlServerCatalogNameOverwrites tag has to be placed inside the configuration tag of the .config file as well.

Note:

For ASP.NET applications, the section declaration has to contain in the type attribute the full type with version and culture, otherwise you'll get an exception at runtime. The specific type declaration is specific for the .NET version you're using and you can find examples how to specify it from the machine.config file in %WINDIR%\Microsoft.NET\Framework\version\CONFIG. For example for .NET 1.1, SqlServer specific: <configSections> <section name="sqlServerCatalogNameOverwrites" type="System.Configuration.NameValueFileSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" /> </configSections>

This example makes sure that at runtime any reference in the persistence info of the elements in the generated code to the catalog 'OldCatalogName1' is renamed to 'NewCatalogName1' and any reference to 'OldCatalogName2' is renamed to 'NewCatalogName2'.

You can also specify an empty string as new name. In that case, the DQE will not specify a catalog name in the generated SQL elements, which will make the SQL target the catalog specified in the connection string.

Schema name overwriting (SqlServer, Oracle, DB2, PostgreSql, Sybase ASA, Sybase ASE)

Besides the ability to rename catalog names, offers LLBLGen Pro also the functionality to rename schema names. This is supported for SqlServer, Oracle PostgreSql, Sybase ASA, Sybase ASE and DB2 databases. These sections work similar to the previously discussed catalog rename feature for SqlServer. Keep in mind that schema renames are global. So you can't rename schema 'dbo' in catalog 'Foo' to 'schema1' and 'dbo' in catalog 'Bar' to 'schema2'.

To setup the renaming of schemas, follow these steps. The first tag in the configuration tag in the .config file has to be the configSections tag. In there, place a section definition tag as shown in the example below. If you also use catalog name renaming, you can place the section definition with the catalog rename section inside the same configSections tag. The following example shows all supported section definitions for schema name overwriting, one for SqlServer, one for DB2, one for Oracle, one for PostgreSql, one for Sybase ASA and one for Sybase ASE. This way, you can define schema overwriting for Oracle, DB2 PostgreSql, Sybase ASA, Sybase ASA and SqlServer in one .config file.

<configSections>
	<section name="sqlServerSchemaNameOverwrites" type="System.Configuration.NameValueSectionHandler" />
	<section name="oracleSchemaNameOverwrites" type="System.Configuration.NameValueSectionHandler" />
	<section name="db2SchemaNameOverwrites" type="System.Configuration.NameValueSectionHandler" />
	<section name="postgreSqlSchemaNameOverwrites" type="System.Configuration.NameValueSectionHandler" />
	<section name="sybaseAseSchemaNameOverwrites" type="System.Configuration.NameValueSectionHandler" />
	<section name="sybaseAsaSchemaNameOverwrites" type="System.Configuration.NameValueSectionHandler" />
</configSections>

You then can define the schema name overwrites in their own section:


You can rename the same schema for different databases to different names. You can also specify an empty string. In that case, the schema name isn't generated into the SQL. For some situations this can be handy, though keep in mind that if you use empty strings for schemas on SqlServer, you also have to specify an empty string for the catalog name in a catalog name overwrite section.

Trigger based sequence values (Oracle/Firebird)

Some Oracle schemas or Firebird databases use triggers to set the sequence value when a record is inserted. LLBLGen Pro's generated code for Oracle or Firebird uses a second query to first determine the next value of the sequence (using NEXTVAL on Oracle, using 1 instead of 0 in GEN_ID on Firebird), then pass that value to the insert query as a normal value. If that code is then used to insert a row in a table with a trigger for sequence values, the trigger will update the inserted value with a new value, making the value returned to the LLBLGen Pro runtime core not the value the trigger inserted into the sequenced field. To overcome this, the Oracle and Firebird Dynamic Query Engines (DQE) can be configured to execute a sequence retrieval query which checks for the current value (using CURRVAL on Oracle, using 0 instead of 1 in GEN_ID on Firebird) after the insert took place, instead of the sequence retrieval query which checks for the next value before the insert takes place.

To do that, add the following tag to the configuration's appSettings section:


A value of false or omitting the tag will cause normal behavior, a sequence call which asks for the next value before the insert.

Ansi joins (Oracle only)

Note:

All other DQE's use ansi-joins by default. This feature therefore is only required for Oracle.

By default the LLBLGen Pro DQE for Oracle 8i/9i produces non-ansi joins (i.e.: SELECT * FROM A, B WHERE A.Foo(+)=B.Foo), when relations are specified. This to use the genated code on 8i as well. Though as there are some problems with non-ansi joins, it's sometimes required to have ansi joins instead (i.e.: SELECT * FROM A RIGHT JOIN B ON A.Foo = B.Foo). With a .config setting, you can signal the DQE to produce ansi joins by default instead. This feature shouldn't be used on Oracle 8i, as Oracle 8i doesn't support ansi joins.

To enable ansi joins, add the following tag to the configuration's appSettings section in the .config file of your application:

<add key="OracleAnsiJoins" value="true" />

A value of false or omitting the tag will cause normal behavior, non-ansi joins, except for the Oracle DQE for Oracle 10g (ODP.NET), which has the default set to true, i.e.: omitting the tag will automatically result in ansi-joins.

Note: The DQE for the MS Oracle provider has this default set to false, even if it's used with Oracle 10g.

DQE Compatibility mode (SqlServer only)

With the arrival of SqlServer 2005 and its new features, it was required to make the SqlServer DQE be configurable so it could generate SQL which was optimal for the database type used. To set the compatibility mode of the SqlServer DQE in the .config file of your application, add the following element to the appSettings section of your application's .config file:

<add key="SqlServerDQECompatibilityLevel" value="number" />

where number is either 0, 1, 2, 3, 4 or 5:

• 0 for SqlServerCompatibilityLevel.SqlServer7
• 1 for SqlServerCompatibilityLevel.SqlServer2000
• 2 for SqlServerCompatibilityLevel.SqlServer2005 (also for 2008, which doesn't require a separate compatibility level)
• 3 for SqlServerCompatibilityLevel.SqlServerCe3x (Sqlserver CE 3.0 and 3.1)
• 4 for SqlServerCompatibilityLevel.SqlServerCe35

The default is 1, or SqlServer2000 so omitting this tag will result in the SqlServer 2000 compatibility mode. Setting the compatibility level controls the sequence retrieval logic to use by default (@@IDENTITY on Sqlserver 7 or SCOPE_IDENTITY() on 2000/2005/2008), the ability to use NEWSEQUENTIALID() (SqlServer 2005 or higher) and the SQL produced for a paging query: a temptable approach is used on SqlServer 7 or 2000, and a CTE approach is used on SqlServer 2005 or higher.

DQE Compatibility mode (Firebird only)

To set the compatibility mode of the Firebird DQE in the .config file of your application, add the following element to the appSettings section of your application's .config file:

<add key="FirebirdDQECompatibilityLevel" value="number" />

where number is either 0 or 1:

• 0 for FirebirdCompatibilityLevel.Firebird15
• 1 for FirebirdCompatibilityLevel.Firebird2x

The default is 0 or Firebird 1.5. This setting will cause no aliases being emitted in subqueries inside SELECT statements as this feature was introduced in Firebird 2.0. If you're using Firebird 2.0 or higher and you want to use Linq to LLBLGen Pro, please set the compatibility mode for Firebird to 1, as Linq to LLBLGen Pro will produce derived tables for some queries which require aliases on fields.

The enum FirebirdCompatibilityLevel is defined in the Firebird DQE assembly as it was introduced during v2.6's release cycle. This location is subject to change in future versions so configure your compatibility through the config file instead of through code.