Breaking changes in LLBLGen Pro v5.6

A small number of breaking changes have been introduced for the supported O/R mapping frameworks in various versions. These changes are documented here per framework and also in the documentation for the particular O/R mapper framework.

Breaking changes in LLBLGen Pro v5.6

Designer

The following breaking changes were made to the designer:

• Visual Studio integration is now only available to Visual Studio 2017 and 2019. Support for integration in 2015 and earlier has been dropped. If you're using 2015 or older, please use the standalone designer.
• Field-mapped-on-related-field settings usage in templates (LLBLGen Pro Runtime Framework specific)
  (TDL Interpreter, used for LLBLGen Pro Runtime Framework) all setting/attribute loops/if statements/normal statements accessing the settings of a Field-mapped-on-a-related-field (Forf) would previously use the settings of the mapped related field instead of the Forf object itself. This has been corrected, as the settings / attributes for the Forf were ignored and there was no way to work around that. If you e.g. have attributes defined on a field that’s mapped through a Forf and therefore rely on these attributes to show up in the generated code, you now have to make sure the same attributes are defined on the Forf itself. See the example below.
  Example: Say you have the relationship Customer.Orders 1:n Order.Customer and the field Customer.CompanyName is mapped in Order through the Field-mapped-on-relatedField CustomerCompanyName. If an attribute [StringLength(40)] is defined on the Customer.CompanyName field, code generated with LLBLGen Pro v5.5 or earlier would have this attribute defined also on the CustomerCompanyName property emitted in the OrderEntity class. Code generated with LLBLGen Pro v5.6 or higher will not have this attribute generated on that field anymore; only if the attribute is defined on the Field-mapped-on-related field Order.CustomerCompanyName will be generated on that property in the OrderEntity class.
• The introduction of automatic clean up of generated files in v5.6 has consequences for people who store custom partial class files with the generated class they're extending in the same folder. Please see Automatic cleanup of outdated files how to work around this and to avoid losing files when generating code.

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v5.6.

• (SelfServicing) EntityBase.UpdateEntity() is now marked as obsolete with error severity, as the method is never called/used. You should override EntityBase.UpdateEntity(IPredicate) instead.

Breaking changes in LLBLGen Pro v5.5

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v5.5.

• CollectionCore.PlaceInRemovedEntitiesTracker() now has an extra parameter, forcePlacement. If you're overriding this method, you have to adjust your override to include this parameter.
• The Debugger visualizers for visual studio 2012 and 2013 have been removed. We now only support Debugger Visualisers for 2015 and up.
• The signatures of DynamicQueryEngineBase.CreateSelectDQ() methods have been changed, some have been removed as part of a refactoring to pass QueryParameters to the engines instead of a series of separate arguments. Normally you won't run into this breaking change, but if you have your own DQE classes, you have to adjust CreatePagingSelectDQ to call CreateSelectDQImpl() instead and make sure the query is generated in an override of CreateSelectDQImpl() (or use the base implementation). Please consult the source code archive for the sources of the shipped DQE engines to see which methods are called where and which arguments to pass.

Breaking changes in LLBLGen Pro v5.4

Designer

The following breaking changes were made to v5.4's designer

• DDL SQL, SQL Server: a DateTime2 field with precision 0 will be generated in the DDL SQL script as a DateTime2(0) and no longer as a DateTime2(7). The DateTime2(7) fallback was used to overcome a bug and keep projects backwards compatible but this caused more harm than good, especially for people who do want to use DateTime2(0).
• PostgreSQL: Npgsql v2.x is no longer supported, you need to use Npgsql 3.x

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v5.4

• If an entity doesn't have Custom Properties defined, the static property CustomProperties isn't available anymore
• If an entity doesn't have a field which has at least one custom property defined, the static property FieldsCustomProperties isn't available anymore
• If an entity doesn't have a field with at least one custom property defined, the property IEntityCore.FieldsCustomPropertiesOfType will return an empty dictionary, instead of a dictionary with for each field an empty dictionary.
• The entity class' property FieldsCustomProperties and IEntityCore.FieldsCustomPropertiesOfType will return a dictionary with entries only for the field(s) which have a custom property defined.
• In the entity classes there's no longer a GetObjectData() method in the generated code. This means the user code region in the method is no longer there. To work around this if you have code in that user code region, define an override of GetObjectData in a partial class of the entity and add the code there. (after calling the base method variant).
• The generated entity classes no longer have a method GetAllRelations() as it was only used by the framework and that functionality has been refactored, so it's no longer needed. If your code needs this functionality, add a partial class to CommonEntityBase and add the following code:

public List<IEntityRelation> GetAllRelations()
{
    return GetEntityStaticMetaData().GetAllRelations();
}

• The generated entity factories no longer have a Create() method which contains a user code region. If you use this region, refactor this code by using a partial class for the factory and override the OnEntityCreated(entity) method and add the code which was otherwise in the user code region to this method. For SelfServicing, the include template 'entityFactoryInclude.template' has been removed.
• Entity factories no longer have a virtual Create() method. If you do customization in a derived Create() method, override CreateImpl() instead, or override OnEntityCreated() to do post-creation customization.
• Adapter: the EntityFieldFactory type has been removed as it's no longer used. The class FactoryClasses\EntityFieldFactory.cs/vb is by default removed from disk by the code generator. If you relied on this class in your own code for the two methods it provided, please enable the setting Project settings -> Conventions -> Entity Model -> LLBLGen Pro Runtime Framework -> Generate entity field factory. When this setting is enabled, the existing class is kept on disk and re-generated with each code generation cycle. It's not needed / used by the runtime framework anymore.
• Adapter: the EntityFieldsFactory type has been removed as it's no longer used. The class FactoryClasses\EntityFieldsFactory.cs/vb is by default removed from disk by the code generator. If you relied on this class in your own code, please enable the setting Project settings -> Conventions -> Entity Model -> LLBLGen Pro Runtime Framework -> Generate entity fields factory. When this setting is enabled, the existing class is kept on disk and re-generated with each code generation cycle. It's not needed / used by the runtime framework anymore.
• SelfServicing: The class TypedListDAO has been moved to the CommonDaoBase class file. The file is actively removed by presets as the class in effect is simply empty.
• All relationclasses have been moved to the entity classes, so for instance the CustomerRelations class is now generated in the file for the CustomerEntity. The folder RelationClasses is removed recursively during code regeneration as it's no longer needed
• The class DynamicRelation is now generated in the HelperClasses folder. For backwards compatibility the namespace is still the same: RelationClasses.
• All entity fieldindex enums are now generated in the entity class file, so for instance the CustomerFieldIndex enum is now generated into the CustomerEntity class file.
• The LinqMetaData class is now generated in the HelperClasses folder. For backwards compatibility the namespace is still the same: Linq. The folder Linq is removed by the code generator, recursively.
• The static Relations property of an entity class returns a static instance now instead of a new instance every time. As the object is stateless, this change shouldn't have any effect on your code except less pressure on the GC.
• Adapter: the cs/vbproj files generated for .NET full for DbGeneric/DbSpecific VS projects are now generated in the DbGeneric / DbSpecific folders and not in the root folder. The preset will actively remove the original files and generate new ones in the new locations. It's recommended to move the vb/csproj files manually to the DbGeneric and DbSpecific folders respectively prior to generating the v5.4 code on top of an existing code base so the code generator will instead of generating new ones, augment the existing ones. This change brings it in line with the .NET standard setup of the code base and makes the projects more suitable for using Nuget packages without conflicts.
• PostgreSQL: Npgsql v2.x is no longer supported, you need to use Npgsql 3.x

Breaking changes in LLBLGen Pro v5.3

Designer

The following breaking changes were in v5.3's designer

• The designer now requires .NET 4.5.2.

Breaking changes in LLBLGen Pro v5.2

No breaking changes were introduced.

Breaking changes in LLBLGen Pro v5.1

In v5.0 the following breaking changes were introduced, documented per supported framework. Breaking changes in older versions are specified later on in this document.

Designer

The following breaking changes have been introduced v5.1's designer

• Derived Models DTO Framework: the generated derived model element classes no longer have the namespaces System.Xml.Serialization and System.Collections.Specialized in the list of using/import namespaces. If you need them to be present, you have to add them to the Additional Interfaces section of the derived model in the Project settings. See: [How to assign additional interfaces / namespaces to elements easily](How To/AssignInterfacesNamespacesToElements.htm)

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v5.1

• The interface member IDbSpecificHintCreator.CreateHintStatement has been marked obsolete and is no longer usable. Please use the FromClauseDirective system instead. This breaking change is likely not impacting anyone, only the people who modified the runtime to add their own table hints. To move to the new FromClauseDirective system, please see the sourcecode of the SQL Server query engine how hints are created in v5.1 onwards.
• QuerySpec: the extension method DynamicQuery<T>.Select(fields) is now marked as obsolete with error trigger, as calling the method on a DynamicQuery<T> is not allowed, the overload shouldn't be in the API as calling the method on a DynamicQuery<T> would overwrite the projection of the query but not the projection lambda. Calling this method is highly likely a mistake in the situation where the user wants to wrap the DynamicQuery<T> with another select. The obsolete message suggests that now. It's not likely you run into this in your code as in earlier versions the method didn't work properly.

Breaking changes introduces in LLBLGen Pro v5.0

In v5.0 the following breaking changes were introduced, documented per supported framework. Breaking changes in older versions are specified later on in this document.

Designer

The following breaking changes were in v5.0's designer

• The designer is now a .NET 4.5 requiring application. It still generates code for .NET 3.5 and up, but running the designer requires .NET 4.5 or higher.
• VS.NET integration now requires VS.NET 2012 or higher. Integration into vs.net 2010 is no longer supported, you need to use the standalone designer in that case.
• DB drivers no longer provide a control for connect information, but instead provide an implementation of a base class for connect information
• Importer plugins no longer provide a control for source location information but instead provide an implementation of a base class for source location information.
• As the setting Sync relational model data element name after rename has changed, renaming a typed view which is mapped onto a table has no effect anymore on the table: the table is only renamed if an entity has been mapped onto it and its name differs from the target table. This is due to the changed nature of synchronizing model elements and relational elements: as a typed view is always reverse engineered from a relational model element it's not leading so the rename shouldn't have any effect, only an entity rename should have.
• The CLIRefresher command line tool has been discontinued. The main reason is that the sync system is a full replacement for both catalog refreshing and model first forward mapping and maintenance and therefore can't be done from the command line anymore. The designer has to be used instead for syncing relational model data with outside sources.
• VS.NET 2008 is no longer supported
• No more support for Sybase iAnywhere (ASA) and Sybase Adaptive Server Enterprise (ASE). The Sybase ASA/ASE Drivers are published on GitHub for the users coming from older LLBLGen Pro versions but they're not supported anymore. We still ship the templates with the designer as it's then more convenient for users to add the drivers without the need to alter templates. It's however not said the templates will stay in future versions nor that they're kept up to date with new features. If new features require extensive changes to the Sybase ASA/ASE Drivers it might be the code is broken and needs manual adjustment. Sybase ASE code repository on GitHub | Sybase ASA code repository on GitHub

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v5.0

• No more support for RIA Services. Microsoft has stopped supporting this framework, which has been abandoned within Microsoft since it's first release, and we do too.
• No more support for Sybase iAnywhere (ASA) and Sybase Adaptive Server Enterprise (ASE). The Sybase ASA/ASE DQEs are published on GitHub for the users coming from older LLBLGen Pro versions but they're not supported anymore. Sybase ASE code repository on GitHub | Sybase ASA code repository on GitHub
• No more DebuggerVisualizers for VS.NET 2008. The Visualizers are no longer supported on VS.NET 2008, we only support VS.NET 2010 and upwards.
• IGeneralDataProjector interface now has a new property RequiresNewObjectArrayPerRow.If you implement your own IGeneralDataProjector deriving classes, you have to implement this property as well. The property signals the projection engine whether a new object[] array has to be allocated with each row. Return true from this property if your projector caches the passed in object[]. Return false if you copy values from the object[] passed in but don't cache it / wrap it in your projector.
• String uniquing/caching in Adapter and SelfServicing has been removed. If you set StringCacheForFetcher properties to a value or to a UniqueList<string> cache in your code, you can safely remove those statements. The main reasons for removing this feature are the following:
  • It actually doesn't save memory: the string read from the datareader is already allocated. If the string cache already contained the string, the cached instance was used, however the already allocated string still occupied memory, which would still need to be garbage collected. So till the next GC.Collect run, this memory was still being allocated, even if string caching was used or not. GC Collect runs in the CLR aren't run often if there's no memory pressure, sometimes it takes longer than 15 minutes or more. With the GC hit still in place, it would only give less memory to be allocated at a given moment by a set of entities or fetched objects if the objects live beyond a GC collect cycle. For these long-lived sets, it's however better to use resultset caching which give faster queries and as they re-use all values fetched, don't re-allocate strings.
    In the general usage of fetching objects, using them, then discarding them, it is highly likely the objects don't live longer than the next time to the GC collect, making the optimization actually not an optimization but a a degration to performance.
  • Uniquing the strings using the UniqueList<string> (still the fastest way to do this) was rather slow: it caused a 20% or more performance hit.
• IDbSpecificGenerator.CreateLikeParameter(string pattern) has been removed; all code should use the overload which accepts the field type.
• OData Support Services are now built against 5.7.0.0 of the Microsoft OData Services v1-3.
• Replacing an entity E1 in a collection C with an entity E2 will now place E1 into the removal tracker collection of C if E1 and E2 have different PK values.

Breaking changes in LLBLGen Pro v4.2

In v4.2 the following breaking changes were introduced, documented per supported framework. Breaking changes in older versions are specified later on in this document.

Designer

The following breaking changes were in v4.2's designer

• Every custom typeshortcut without a default value defined on it, will cause existing default constraints to be dropped. To work around this, define a default value for the custom typeshortcut in the project settings, which is equal to the existing one. See "Working with types and default values using Type Shortcuts" for details.
• The FrameworkValidatorBase class has methods with different signatures for creating a message for errors/warnings: they now require a warningcode, which may be empty if the message is an error message.
• The PluginBase class has methods with different signatures for creating a message for errors/warnings: they now require a warningcode, which may be empty if the message is an error message.

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v4.2

• A unit of work will now report the actually deleted entities more precisely. If an entity was denied to be deleted, it no longer is included in the amount of entities deleted.
• The SelfServicing DaoBase class' ctor now requires an instance to the persistenceinfoprovider class. This is normally provided by the generated CommonDaoBase class. In case you use a custom CommonDaoBase class template, you have to adjust your template accordingly. See the CommonDaoBase template ctor call how to do that.
• IResultsetCache has been updated with additional methods to implement new features. If you implement this interface, you have to implement the additional new methods as well. See the ResultsetCache class in the ORM Support Classes for details how to do that.
• Adapter specific: The two-class scenario for Adapter has been deprecated and it's not recommended you use it anymore as no new features in v4.2 have been added to the specific templates for this scenario. Instead use partial classes. The preset is still available, if you need to upgrade to v4, however it's highly recommended you refactor your code to move to partial classes and use the General preset instead for adapter. The code generated with the Two-class scenario preset for Adapter will work, however won't contain Tvf calls for Linq nor does it support Linq queries / query spec queries for e.g. typed lists. The preset is in a separate folder 'Deprecated'. The templates are also moved to a Deprecated folder. The templates are now found in a deprecated templatebindings file, and it's not recommended to use these templates.
• OData support classes: The OData Support Classes are now built against WCF Data Services server v5.6.1 (was v5.6.0). If you need OData v4 support, you manually have to compile the OData Support Classes against the v6.x assembly on nuget.

Breaking changes in LLBLGen Pro v4.1

In v4.1, the following breaking changes were introduced, documented per supported framework. Breaking changes in older versions are specified later on in this document.

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v4.1

• Multiple .Take() calls on a query in Linq will no longer result in 'last Take wins' but will use the lowest number of the Take calls.

  Example:

  metaData.Customer.Take(10).Take(20);
  

  Original behavior (v2.6-4.0): would result in 20 rows. New behavior (v4.1+): results in 10 rows, as taking 20 rows from a set of at most 10 rows should never result in 20 rows. If your code relies on the original behavior, set LLBLGenProProviderBase.AlwaysUseLastSpecifiedTake to true (default is false).

• OData Support Classes are now build against WCF Data Services 5.6.0.

Breaking changes in LLBLGen Pro v4.0

In v4.0, the following breaking changes were introduced, documented per supported framework. Breaking changes in older versions are specified later on in this document.

Designer

The following breaking changes have been in v4.0's designer

• The designer requires .NET 4.0 or higher to run.
• .NET 2.0 and .NET 3.0 are no longer supported.
• The template ID's for VS.NET templates for the LLBLGen Pro Runtime Framework which referred to a VS.NET version have been changed and no longer have the VS.NET version in the template ID: e.g. SD_VsNet2008Template is now SD_VsNetTemplate. You'll run into this when you migrate your own presets from v3.x to v4. To correct this, simply change the template ID on the vs.net project task in the preset so it doesn't have the VS.NET version in the templateID. To check which template IDs are available, please use the Template Bindings Viewer, or tab 2 of the code generation configuration dialog (advanced view). 

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v4.0. They are a result of refactoring a lot of code of the entity classes and related classes of both Adapter and SelfServicing for faster fetch operations. In general these breaking changes aren't affecting most users, only the people who have extended some classes or overriden the methods affected. Correcting these changes is easy and straight forward.

General breaking changes

• Entity.Validate() has been made protected. It's now a mandatory deprecated method (causes a compilation error) since v2.6 and starting with v4 the method is no longer available. EntityCore. AddInternalsToContext() now has a parameter, resetWhenNull.
• UnitOfWork(2).Commit doesn't throw ORMConcurrencyExceptions anymore if a delete of an entity doesn't succeed because the entity was already deleted and no restriction was specified. The exception is still thrown if a restriction has been specified and an entity delete results in 0 rows affected.
• Excluded fields are now enlisted in the resultset as: NULL as fieldname. This means the resultset layout is always the same, excluded fields or not. In general this isn't a breaking change,\ but if you rely on the resultset not having NULL values for excluded fields, your code needs adjustment. The change was made to make the resultset always be the same, to make code consuming the resultset easier and faster.
• DbSpecificCreatorBase.CreateValidAlias(string, bool) has been removed (also from the interface IDbSpecificCreator), instead simply use CreateValidAlias(string) and in your override of that method always check for quotes. As all DQEs now check for quotes in the alias method, if you created your own DQE and used the override with the boolean parameter, use the CreateValidAlias(string) instead.
• Several virtual methods have had their signature changed due to the introduction of QueryParameters. Normally you won't notice this, unless you've overriden methods which now receive a QueryParameters object instead of a list of parameters. To fix this,refactor your override to accept the QueryParameters object, which contains all the parameter objects which were previously passed into the method.
• DynamicQueryEngineBase.CreateInsertDQ/CreateUpdateDQ always created a BatchActionQuery, even if there was just 1 target. We refactored it to let it create only a BatchActionQuery if there are multiple targets, as the code was intended to do when it was first written back in 2005. In general you won't run into this change, unless your code relies on the fact the query created is always a BatchActionQuery. Instead, use the interface IActionQuery to work with the object returned. EntityCollection<T> / entityNameCollection.AddRange(IEnumerable) now doesn't raise a ListChanged.ItemAdded event after each item added to the collection, but one ListChanged.Reset event after all items have been added. This makes sure a bound EventView(2) won't update itself after each addition but just once.
• Linq related: the test for correlation predicates in nested queries is now more strict: it now also tests the operator of the predicate to be 'Equal', previously it didn't do that, it accepted any Field op Field predicate, which could lead to queries being accepted but with potentially wrong query results.

Breaking changes related to refactor EntityFields for faster fetches

• EntityFields(2).Contract() and .Compact() methods are no longer supported on EntityFields(2) objects which are part of an entity object. Expand() is still supported in that situation. In practice this has no high impact on existing code as entity classes which use fields objects with extra fields added to them in code don't contract/compact.
• EntityFields(2)[index] setter won't place the specified field object on the index specified, if the fields object is part of an entity, it will copy the value instead.
• EntityFields(2).IsDirty and .State are only vaild when the fields object is part of an entity. This is logical, as they make no sense when the fields object is used to build a query.
• IEntityFieldCore no longer has the methods AcceptChange and RejectChange. The pattern in which these methods are used never really worked properly anyway, and it's highly unlikely these methods are used in user code. If you use these methods, use SaveFields/RollbackFields instead.
• EntityCore. PreProcessValueToSet and EntityCore.PostProcessValueToGet no longer accept a field instance, but instead accept the IFieldInfo object of the field. This fieldinfo object, which contains the field index, can then be used to obtain the values and field info from the Fields object. This is done to avoid unnecessary field access internally, as fields are no longer created by default inside an entity. Use the field index to obtain values from the entity.Fields object through its IEntityFieldsCore interface.
•  EntityCore.OnFieldValueChanged no longer accepts a field, but instead accepts the IFieldInfo of the field which value was set.
• The virtual method ReadRowIntoFields in DataAccessAdapterBase/DaoBase been removed. The method was only called when single entities were fetched, the multi-entity fetch pipeline skipped it altogether.

How to work with the EntityFields(2) objects without using entity fields in an entity

If your code accesses the entity field objects in e.g. validators or auditors, instead of reading field properties, you can now access the values you need directly from the entity.Fields object through its IEntityFieldsCore interface, instead of obtaining the EntityField(2) object and access its properties.

The reason you should use IEntityFieldsCore's methods instead of obtaining a field object from the Fields object is that entity objects no longer create entity field objects by default. They use a new internal object which is more efficient and allows faster entity materialization after a fetch. When you use entity.Fields[index] the Fields object will create a new field object for you on the fly, through which you can access the information you needed. However creating this field object is unnecessary.

In general this means you should use methods like entity.Fields.GetCurrentValue(index) instead of entity.Fields[index].CurrentValue. The latter still works, but creates an EntityField(2) object, the former doesn't. Please see for details about the IEntityFieldsCore interface, the LLBLGen Pro Runtime Framework Reference Manual (LLBLGenPro.RTL.ReferenceManual.chm).

LinqSupportClasses and QuerySpec assemblies are now merged into ORMSupportClasses assembly

Starting with v4, the SD.LLBLGen.Pro.LinqSupportClasses assembly and the SD.LLBLGen.Pro.QuerySpec assembly are now merged into the SD.LLBLGen.Pro.ORMSupportClasses assembly. This makes things easier when referencing assemblies. If you migrate an existing v2.6 or v3.x code base to v4, you have make sure the references to the LinqSupportClasses and QuerySpec assemblies are removed as they're no longer needed.

.NET 3.5 is now required; no more support for .NET 2.0 or .NET 3.0.

Starting with v4, the LLBLGen Pro runtime framework is compiled against .NET 3.5, and your software therefore requires .NET 3.5 as well. If you're migrating an existing code base to v4, you have to adjust the target framework in Visual Studio to at least .NET 3.5

SD.LLBLGen.Pro.ORMSupportClasses and DQE assemblies no longer have .NETxy suffix in file/assembly name

Starting with v4, the ORMSupportClasses and DQE assemblies no longer have a .NETxy suffix in the assembly and file name. If you specify the assembly names for references in webforms, you have to adjust them so they don't contain '.NET20' anymore.

SD.LLBLGen.Pro.ODataSupportClasses is now compiled against v5.3 of the WCF Data Services Server assembly

Starting with v4, the ODataSupportClasses have been compiled against v5.3 of the WCF Data Services Server assembly available from nuget, instead of the .NET 4 version of the same assembly. Your application will therefore need to reference this same assembly (or newer) to use ODataSupportClasses. The advantage is that you get OData v3 support out of the box, while still are able to use OData v1 and v2.

TDL Interpreter / parser code freeze

Starting with v4, no new functionality, except some small changes, has been added to the TDL interpreter / TDL parser. All new functionality will be written in .lpt templates. If you use the TDL interpreter in your templates, be aware that if you want to utilize new features like Table valued functions in your TDL templates you have to rewrite them in .lpt templates instead. It's possible to use an .lpt include template inside a TDL template.

Breaking changes in LLBLGen Pro v3.5

In v3.5, the following breaking changes were introduced, documented per supported framework. Breaking changes in older versions are specified later on in this document.

NHibernate

If you're using the type converter which was shipped with v3.x, your project won't load properly (missing type converter) when you load your project into LLBLGen Pro v3.5. This is caused by the fact that there's no type converter dll shipped for NHibernate anymore, as the dll had a dependency on the NHibernate dll with a specific version which made it cumbersome to use.

To solve this, you can do one of the following things:

• manually compile the NHibernate type converter sourcecode from the v3.5 sourcecode package (TypeConverters\Nhibernate folder) and place the type converter dll into the TypeConverters folder of v3.5, or use the sourcecode included in the NHibernate Support manual shipped with LLBLGen Pro.
• Copy the v3.1 typeconverter for NHibernate dll into the TypeConverters folder of v3.5.

LLBLGen Pro Runtime Framework

The following breaking changes have been in LLBLGen Pro Runtime Framework v3.5. They are a result of refactoring a lot of code of the entity classes and related classes of both Adapter and SelfServicing into a base class which is inherited by EntityBase and EntityBase2 so more code is re-used. In general these breaking changes aren't affecting most users, only the people who have extended some classes or overriden the methods affected. Correcting these changes is easy and straight forward.

Changed method signatures

• EntityBase.OnFieldValueChanged and EntityBase2.OnFieldValueChanged. The new method uses IEntityFieldCore instead of IEntityField/IEntityField2.
• EntityBase.PreProcessValueToSet and EntityBase2. PreProcessValueToSet. The new method uses IEntityFieldCore instead of IEntityField/IEntityField2.
• EntityBase.PostProcessValueToGet and EntityBase2. PostProcessValueToGet. The new method uses IEntityFieldCore instead of IEntityField/IEntityField2.
• EntityBase. SetRelatedEntityProperty and EntityBase. SetRelatedEntityProperty. The new methods use IEntityCore instead of IEntity or IEntity2.
• EntityBase WriteXml(XmlWriter writer, XmlFormatAspect aspects, string rootNodeName, Dictionary<Guid, IEntity> processedObjectIDs) and EntityBase WriteXml(XmlWriter writer, XmlFormatAspect aspects, string rootNodeName, Dictionary<Guid, IEntity2> processedObjectIDs). The new methods use IEntityCore instead of IEntity or IEntity2.
• AuditorBase.WriteXml. The new method now uses IEntityCore instead of IEntity2.
• EntityBase.PostReadXmlFixups. The method is now called PerformPostReadXmlFixups.
• EntityBase/EntityBase2.OnRelatedEntitySet/OnRelatedEntityUnset. The methods now have as entity type IEntityCore instead of IEntity or IEntity2.
• EntityBase/EntityBase2.SetRelatedEntity/UnsetRelatedEntity. The methods now have as entity type IEntityCore instead of IEntity or IEntity2.
• EntityBase/EntityBase2.OnSetRelatedEntityProperty. The method now has as entity type IEntityCore instead of IEntity / IEntity2.
• ObjectGraphUtils methods. The methods in ObjectGraphUtils are now mostly generic methods returning generic objects. In general this doesn't have to be a problem, as the class is not often used outside the runtime. If you get compilation issues, specify the generic type explicitly, e.g.:

Dictionary<Type, IEntityCollection2> entitiesPerType =
                    graphUtils.ProduceCollectionsPerTypeFromGraph<IEntityCollection2>(this);

No more COM+ support

All COM+ oriented code has been deprecated and is no longer included. This means that projects migrated to v3.5 and which are re-generated have to get rid of the COM+ based classes (automatic in Adapter, in SelfServicing, remove the TransactionComPlus helper class). COM+ using code should use System.Transactions instead.

ORMSupportClasses assembly is now split in two assemblies

To make the ORMSupportClasses and the generated code projects usable in .NET 4 client profile projects, we split up the ORMSupportClasses assembly into two assemblies:

• SD.LLBLGen.Pro.ORMSupportClasses.NET20.dll The normal dll which contains all the base classes for using the generated code
• SD.LLBLGen.Pro.ORMSupportClasses.Web.dll The assembly which now contains the DataSource classes for Web usage and accompanying designers.

The net effect is that for web projects migrated to v3.5 which use the datasource controls, the assembly name of the datasource declaration has to change from SD.LLBLGen.Pro.ORMSupportClasses.NET20 to SD.LLBLGen.Pro.ORMSupportClasses.Web. Additionally, the version has to be adjusted to v3.5.0.0.

In general this change has to be made in the web.config file of the website. It's recommended to register the tag prefix 'llblgenpro' in the web.config file so you'll have the reference to the assembly in just 1 location, instead of on every page where a datasource control is used. In the case where the tag is registered on every page, the assembly name has to be changed in every <Register> element as described above.

To perform design-time actions, the datasource controls located in SD.LLBLGen.Pro.ORMSupportClasses.Web.dll have to be added to the toolbox, which makes them available when a webform is opened in VS.NET.

No more design time support for Entity Collection classes.

The Entity Collection classes no longer support design-time usage through a designer in VS.NET. In general it's not a good idea to drag an entity collection onto a Windows Form anyway, but in the past you could do so and, in adapter's case, get a designer which allowed you to pick the factory.

In v3.5 there's no longer design-time support for collections. In general this shouldn't be a big problem, as best practices say you should use the Data sources feature in VS.NET for this anyway: Instead of dragging/dropping an entity collection, configuring it at design time and at runtime filling it with data, do the following:

1. Create a data source in the VS.NET project using the Data menu
2. Select the entity type you want to bind through the data source
3. Add a BindingSource to the form you want to bind entity data.
4. Select the created data source as the DataSource of the binding source.
5. Set the BindingSource as the DataSource of the control you want to bind to.
6. At runtime, bind a new entity collection to the BindingSource instance by setting the DataSource property of the BindingSource to the entity collection instance:

   var toBind = new EntityCollection<CustomerEntity>();
   // fetch it
   ...
   // bind it to the bindingsource
   myBindingSource.DataSource = toBind;    
   

Projects migrated to v3.5 continue to work, but altering the design-time designed collections won't work as there aren't any designers anymore.

Obsolete methods

• The method entity.TestCurrentFieldValueForNull has been marked Obsolete, as the method is unnecessary. It will give a warning if you call this method in your code. Instead of calling this method, please use entity.Field==null.
• The method entity.CheckIfCurrentFieldValueIsNull has been marked Obsolete, as the method is unnecessary. It will give a warning if you call this method in your code. Instead of calling this method, please use entity.Field==null.

Breaking changes in LLBLGen Pro v3.1

In v3.1, the following breaking changes were introduced, documented per supported framework.

Entity Framework, LLBLGen Pro Runtime Framework

In v3.0, when using multiple RDBMS types in a project (e.g. SqlServer and Oracle), generating code would result in database specific vs.net projects which have the database type name (e.g. ‘SqlServer’) twice e.g. MyRootNamespace.SqlServerSqlServer.Persistence.csproj). This has now been corrected. If you use multiple RDBMS types in your project and one of these target frameworks (Linq to Sql, Entity Framework or LLBLGen Pro runtime framework), generating code with v3.1 will result in a database specific project name with the database type name just once (so MyRootNamespace.SqlServer.Persistence.csproj for example).

Existing solutions will refer to the old vs.net project file, so you manually have to correct the solution.

To make it easy: before generating code with v3.1, rename your persistence projects so that the RDBMS type name is specified just once. Do this in vs.net, so the .sln file is updated as well. After that, regenerate code with v3.1, so the code generator will update your existing vs.net projects.

If you don’t want this: in the preset you use, specify [databaseShortName] in the filename parameter for the vs.net project task in the preset at the spot after [projectName] or where the redundant name was specified. Then save the preset as a custom preset and use this preset from now on.

NHibernate

In v3.0, vs.net projects were named after the LLBLGen Pro project name. This has been changed, to make this consistent with the rest of the frameworks. Starting with v3.1, projects are named using the root namespace specified in the code generation dialog as the ‘project name’. So if your LLBLGen Pro project is called ‘MyProject’, and you specify as root namespace ‘MyCompany.Foo’, in v3.0, the vs.net projects were named MyProject.Model.csproj and MyProject.Persistence.csproj. In v3.1 they’re called MyCompany.Foo.Model.csproj and MyCompany.Foo.Persistence.csproj. This is a breaking change for existing projects, as the existing solutions refer to the old vs.net project files.

To make it easy: before generating code with v3.1, rename your vs.net projects generated with v3.0 after the root namespace specified, using the pattern: rootnamespace.Model.cs/vbproj and rootnamespace.Persistence.cs/vbproj. Do this in vs.net so the .sln file is updated automatically. After that, generate code with v3.1

If you don’t want this: set the parameter useRootNameSpaceForProjectName to false (it was set to false in v3.0’s preset, it’s now set to true by default) for the vs.net project tasks in the preset you’re using, then save it as a custom preset and keep using that preset from now on. Doing this has the side effect that the assembly name in the generated vs.net project is not correctly reflecting the RDBMS type if you use multiple RDBMS types in your project. So you have to manually alter this to work around the fact you get assemblies with the same name for every persistence project in your solution. Normally this isn’t a problem if you use just one database type in your project.

LLBLGen Pro Runtime Framework

The following breaking changes are specific for the LLBLGen Pro Runtime Framework

Type converters

If you use type converters, make sure that they can handle null (Nothing in VB.NET) values: type converters now get passed in null (Nothing in VB.NET) instead of DBNull.Value. This was actually already a breaking change in v3.0.

SQL Server DQE

The static property DynamicQueryEngine.CompatibilityLevel has been renamed to DynamicQueryEngine.DefaultCompatibilityLevel. A new, instance property has been added, CompatibilityLevel which sets the compatibility level per instance. It’s not likely you run into this, as it’s recommended to set the compatibility level in the config file or once through the DataAccessAdapter class or CommonDaoBase class.