Release Bulletins for SnapObjects

Last Updated: January 2024

This document provides release bulletins for all versions of SnapObjects (including the following NuGet packages: SnapObjects.Data, SnapObjects.Data.AspNetCore, SnapObjects.Data.SqlServer, SnapObjects.Data.PostgreSql, SnapObjects.Data.Oracle, SnapObjects.Data.Informix, SnapObjects.Data.Odbc, SnapObjects.Data.MySql, and SnapObjects.Data.Sqlite).

Installation of SnapObjects

• The instructions on how to install, update, and uninstall the SnapObjects packages are the same as all the other NuGet packages. Please refer to the SnapDevelop documentation at https://docs.appeon.com/snapdevelop2022r3/SnapDevelop_Users_Guide/Chapter2Working_with_solutions_and_projects.html#managing-nuget-packages.

SnapObjects 4.2.0

Released in January 2024.

What's New

• Internal updates only.

SnapObjects 4.1.0

Released in August 2023.

What's New

• Internal updates only.

SnapObjects 4.0.0

Released in September 2022.

What's New

• Internal updates only.

SnapObjects 3.1.2

Released in January 2022.

Bug Fixes

SnapObjects 3.1.2 has the following bug fixes:

• (Bug ID: 7507) When the Oracle stored procedure out parameter is the char(1) type, the result set will contain redundant spaces.
• (Bug ID: 6917) If the Composite DataWindow has data source, the following retrieval error occurs: Unable to cast object of type 'System.Decimal' to type 'System.Double'.

SnapObjects 3.1.1

Released in November 2021.

What's New

• Internal updates only.

SnapObjects 3.1.0

Released in July 2021.

Database Server Requirements

The SnapObjects NuGet packages can connect with the following databases using the specified data provider:

DB Type	Data Provider
MySQL 5.6, 5.7, or 8.0 Amazon RDS for MySQL 8.0.20 Amazon Aurora for MySQL 5.6.10a Azure Database for MySQL 5.6	SnapObjects.Data.MySql.dll
PostgreSQL 9.6, 10.1, 11.3, or 12 Amazon RDS for PostgreSQL 12.3-R Amazon Aurora for PostgreSQL 11.6 Azure Database for PostgreSQL 11	SnapObjects.Data.PostgreSql.dll
Oracle 12c, 18c, or 19c Amazon RDS for Oracle 12.1.0.1	SnapObjects.Data.Oracle.dll
SQL Server 2016, 2017, or 2019 Amazon RDS for SQL Server 2017 14.00.3281.6.v1 Azure SQL Database (Latest SQL Server engine as at September, 2020)	SnapObjects.Data.SqlServer.dll
SQLite 3	SnapObjects.Data.Sqlite.dll
Informix 12.x or 14	SnapObjects.Data.Informix.dll
Adaptive Server Enterprise 16.0	SnapObjects.Data.Odbc.dll
SQL Anywhere 16 (16.0.0.2043 or later) or 17	SnapObjects.Data.Odbc.dll
HANA 2.0	SnapObjects.Data.Odbc.dll

What's New

• Provides the SnapObjects.Data.Informix.dll data provider to connect with the Informix database (64-bit Windows only).
• Adds OutJoinSyntax.
• IQueryBuilder.RemoveWhere<TModel>() method is obsolete. Replace it with ISqlModelMapper.GetQueryBuilder<TModel>(true).
• Adds the MySqlDataContextOptions.IgnoreSpace property and MySqlDataContextOptions<TAdoDbContext>.IgnoreSpace property.
• Adds the OracleDataContextOptions.SuppressGetDecimalInvalidCastException property and OracleDataContextOptions.InitialLOBFetchSize property.

Known Issues

SnapObjects 3.1.0 has the following known issues:

• SnapObjects can only connect with the Informix database in a 64-bit Windows OS (not in 32-bit OS).
• When there is only one retrieval argument in SqlModelMapper, a null value cannot be passed as the value for the retrieval argument.

Bug Fixes

SnapObjects 3.1.0 has the following bug fixes:

• (Bug ID: 5928) After converted to C# models, the DataObject with RIGHT OUTER JOIN retrieves the wrong row count.
• (Bug ID: 5881) The DataWindow Sort expression using a retrieval argument causes an exception in Retrieve().
• (Bug ID: 5945) After converted to C# models, the DataObject with LEFT OUTER JOIN in UNION retrieves the wrong row count.
• (Bug ID: 5887) When the Where clause for Update/Delete is set to Key and Modified Columns, it adds a column that is not part of the updatable table.
• (Bug ID: 6022) No property can map to the column in converted DataObject if the computed field has the same name as the database field.
• (Bug ID: 6328) When DelimitIdentifier='Yes', Update cannot find the corresponding table.
• (Bug ID: 6010) SnapObjects 3.0 references .NET Core 2.1 packages (rather than .NET Core 3 packages).

SnapObjects 3.0.0

Released in January, 2021

What's New

Support for dynamic queries with SqlModelMapper

The following interfaces are added to support dynamic queries with SqlModelMapper:

• IQueryBuilder<TModel>: Provides methods to add or remove query conditions for a dynamic query.
• IQueryAndOrBuilder<TModel>: Adds query conditions to the WHERE clause of a SQL statement using the AND or OR operator.
• IQueryWhereBuilder<TModel>: Provides methods to add the WHERE clause for a dynamic query, or to check if the WHERE clause already exists or is null.
• ISqlBuilderLoader<TModel>: Provides methods to retrieve data by a dynamic query.

The following method is added to the ISqlModelMapper interface and returns the query conditions of a dynamic query:

• IQueryBuilder<TModel> GetQueryBuilder<TModel>();

Support for ASE and HANA databases

The following classes are added to support SAP ASE:

• OdbcAseDataContext
• OdbcAseDataContextOptions
• OdbcAseDataContextOptions<TAdoDbContext>
• OdbcAseExtensions

The following classes are added to support SAP HANA:

• OdbcHanaDataContext
• OdbcHanaDataContextOptions
• OdbcHanaDataContextOptions<TAdoDbContext>
• OdbcHanaExtensions

For the supported ASE and HANA versions, refer to https://docs.appeon.com/snapdevelop2021/Installation_Guide/index.html#database-server-requirements.

Support for cloud databases

The following packages are enhanced to connect databases in a cloud environment:

• SnapObjects.Data.MySql: Supports Amazon Aurora for MySQL, Amazon RDS for MySQL, and Microsoft Azure Database for MySQL.
• SnapObjects.Data.PostgreSql: Supports Amazon Aurora for PostgreSQL, Amazon RDS for PostgreSQL, and Microsoft Azure Database for PostgreSQL.
• SnapObjects.Data.Oracle: Supports Amazon RDS for Oracle.
• SnapObjects.Data.SqlServer: Supports Amazon RDS for SQL Server and Microsoft Azure SQL Database.

For the supported versions of each type of cloud database, refer to https://docs.appeon.com/snapdevelop2021/Installation_Guide/index.html#database-server-requirements.

Enhanced ParamValue methods

The parameter value in the following ParamValue methods is changed to generic type:

• ParamValue New<TType>(string name, TType value, ParameterDirection direction = ParameterDirection.Input);
• ParamValue Input<TType>(string name, TType value);
• ParamValue InputOutput<TType>(string name, TType value);

New class for SnapObjects.Data.Oracle

A new class named ParamValueExtensions is added to the package SnapObjects.Data.Oracle. The following method is included for setting the maximum size of each array element in the ParamValue.

• void SetArrayBindSize(this ParamValue paramValue, int[] arrayBindSize);

New async methods for SqlExecutor

The following asynchronous methods are added to the ISqlExecutor interface:

• Task<TValue> ScalarAsync<TValue>(sqlText, params object[] parameters);
• Task<TValue> ScalarAsync<TValue>(string sqlText, object[] parameters, CancellationToken cancellationToken);
• Task<TValue> ScalarAsync<TValue>(ISqlQueryBuilder sqlQueryBuilder, params object[] parameters);
• Task<TValue> ScalarAsync<TValue>(ISqlQueryBuilder sqlQueryBuilder, object[] parameters, CancellationToken cancellationToken);
• Task<IList<TModel>> SelectAsync<TModel>(string sqlText, params object[] parameters);
• Task<IList<TModel>> SelectAsync<TModel>(string sqlText, object[] parameters, CancellationToken cancellationToken);
• Task<IList<TModel>> SelectAsync<TModel>(ISqlQueryBuilder queryBuilder, params object[] parameters);
• Task<IList<TModel>> SelectAsync<TModel>(ISqlQueryBuilder queryBuilder, object[] parameters, CancellationToken cancellationToken);
• Task<TModel> SelectOneAsync<TModel>(string sqlText, params object[] parameters);
• Task<TModel> SelectOneAsync<TModel>(string sqlText, object[] parameters, CancellationToken cancellationToken);
• Task<TModel> SelectOneAsync<TModel>(ISqlQueryBuilder queryBuilder, params object[] parameters);
• Task<TModel> SelectOneAsync<TModel>(ISqlQueryBuilder queryBuilder, object[] parameters, CancellationToken cancellationToken);
• Task<int> ExecuteAsync(string sqlText, params object[] parameters);
• Task<int> ExecuteAsync(string sqlText, object[] parameters, CancellationToken cancellationToken);
• Task<int> ExecuteProcedureAsync(string procedureName, params object[] parameters);
• Task<int> ExecuteProcedureAsync(string procedureName, object[] parameters, CancellationToken cancellationToken);
• Task<IList<TModel>> SelectProcedureAsync<TModel>(string SelectProcedureAsync, params object[] parameters);
• Task<IList<TModel>> SelectProcedureAsync<TModel>(string SelectProcedureAsync, object[] parameters, CancellationToken cancellationToken);

The following asynchronous methods are now available for .NET Standard 2.1 or higher:

• IAsyncEnumerable<TModel> SelectLazyAsync<TModel>(ISqlQueryBuilder queryBuilder, params object[] parameters);
• IAsyncEnumerable<TModel> SelectLazyAsync<TModel>(ISqlQueryBuilder queryBuilder, object[] parameters, CancellationToken cancellationToken);
• IAsyncEnumerable<TModel> SelectLazyAsync<TModel>(string sqlText, params object[] parameters);
• IAsyncEnumerable<TModel> SelectLazyAsync<TModel>(string sqlText, object[] parameters, CancellationToken cancellationToken);

New async methods for SqlModelMapper

The following asynchronous methods are added to the ISqlModelMapper interface:

• Task<ILoadable<TModel>> LoadAsync<TModel>(params object[] parameters);
• Task<ILoadable<TModel>> LoadAsync<TModel>(object[] parameters, CancellationToken cancellationToken);
• Task<ILoadable<TModel>> LoadByPageAsync<TModel>(int currentIndex, int pageSize, params object[] parameters);
• Task<ILoadable<TModel>> LoadByPageAsync<TModel>(int currentIndex, int pageSize, object[] parameters, CancellationToken cancellationToken);
• Task<ILoadable<TModel>> LoadAllAsync<TModel>();
• Task<ILoadable<TModel>> LoadAllAsync<TModel>(CancellationToken cancellationToken);
• Task<ILoadable<TModel>> LoadAllByPageAsync<TModel>(int currentIndex, int pageSize);
• Task<ILoadable<TModel>> LoadAllByPageAsync<TModel>(int currentIndex, int pageSize, CancellationToken cancellationToken);
• Task<ILoadable<TModel>> LoadByKeyAsync<TModel>(params object[] parameters);
• Task<ILoadable<TModel>> LoadByKeyAsync<TModel>(object[] parameters, CancellationToken cancellationToken);
• Task<TValue> ScalarAsync<TModel, TValue>(string expression, params object[] parameters);
• Task<TValue> ScalarAsync<TModel, TValue>(string expression, object[] parameters, CancellationToken cancellationToken);
• Task<TValue> ScalarByKeyAsync<TModel, TValue>(string expression, params object[] parameters);
• Task<TValue> ScalarByKeyAsync<TModel, TValue>(string expression, object[] parameters, CancellationToken cancellationToken);
• Task<IDbResult> SaveChangesAsync();
• Task<IDbResult> SaveChangesAsync(CancellationToken cancellationToken);

The following asynchronous methods are added to the IEmbeddedLoadable interface:

• Task<IEmbeddedLoadable<TModel>> IncludeAsync(Expression<Func<TModel, object>> property, bool cascade = false, CancellationToken cancellationToken = default);
• Task<IEmbeddedLoadable<TModel>> IncludeAllAsync(bool cascade = false, CancellationToken cancellationToken = default);

The following asynchronous methods are added to the ILoadable interface:

• Task<ILoadable<TModel>> IncludeAsync(Expression<Func<TModel, object>> property, bool cascade = false, CancellationToken cancellationToken = default);
• Task<ILoadable<TModel>> IncludeAsync(int index, Expression<Func<TModel, object>> property, bool cascade = false, CancellationToken cancellationToken = default);
• Task<ILoadable<TModel>> IncludeAllAsync(bool cascade = false, CancellationToken cancellationToken = default);
• Task<ILoadable<TModel>> IncludeAllAsync(int index, bool cascade = false, CancellationToken cancellationToken = default);

New async methods for SqlBuilder

The following asynchronous methods are added to the ISqlBuilderBase interface:

• Task<bool> ValidateAsync(DataContext context, bool throwError = true);
• Task<bool> ValidateAsync(DataContext context, bool throwError, CancellationToken cancellationToken = default);

New async methods for DataContext

The following asynchronous methods are added to the DataContext class:

• Task<IAdoDbTransaction> BeginTransactionAsync();
• Task<IAdoDbTransaction> BeginTransactionAsync(CancellationToken cancellationToken);
• Task<IAdoDbTransaction> BeginTransactionAsync(IsolationLevel isolationLevel);
• Task<IAdoDbTransaction> BeginTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken);

New async methods for IAdoDbConnection

The following asynchronous methods are added to the IAdoDbConnection interface:

• Task<bool> OpenAsync();
• Task<bool> OpenAsync(CancellationToken cancellationToken);
• Task<bool> CloseAsync();
• Task<bool> CloseAsync(CancellationToken cancellationToken);

New async methods for IAdoDbTransaction

The following asynchronous methods are added to the IAdoDbTransaction interface (for .NET Standard 2.1 or higher):

• Task CommitAsync();
• Task CommitAsync(CancellationToken cancellationToken);
• Task RollbackAsync();
• Task RollbackAsync(CancellationToken cancellationToken);

New async methods for IAdoDbTransactionManager

The following asynchronous methods are added to the IAdoDbTransactionManager interface:

• Task<IAdoDbTransaction> BeginTransactionAsync(CancellationToken cancellationToken);
• Task<IAdoDbTransaction> BeginTransactionAsync(IsolationLevel isolationLevel, CancellationToken cancellationToken = default);

Bug Fixes

• (Bug 4869) Failed to format DateTime using [shortdate] or [longdate] in DwCompute.
• (Bug 5222) ImportString did not use the default DataStore template when importing XML data.
• (Bug 5364) The exception message thrown by DwTemplateImporter was not clear enough when the value assigned to a column did not match the column’s type.

SnapObjects 2.1.0

Released in July 2020.

What's New

• The IDataContextOptions interface has two new properties: DelimitIdentifier and TrimSpaces.
• The ConnectionString property of the IDataContextOptions interface is changed from {get; set;} to {get;}.
• The OracleDataContextOptions class has a new property: InitialLongFetchSize.
• New extension methods have been added to IDataContextOptions for the supported database types.

Bug Fixes

• (Bug 4366) Data types incompatible in the SqlExecutor.Scalar method (e.g., unable to cast object of type 'System.Int16' to type 'System.Nullable'1[System.Int32]').
• (Internal bug) When SQL query is executed, exception occurs if the names of two or more columns are the same in the SQL statement.
• (Internal bug) Failure to convert the OracleDecimal data type (generated when Oracle executes such aggregate functions as Avg and Sum) to the Decimal data type.

SnapObjects 2.0.0

Released in April 2020.

What's New

• UpdateWhereStrategyAttribute (UpdateWhereStrategy strategy) is added for model class.
• ISqlModelMapper supports to track DataStore.
• SqlExecutor.SelectLazy returns an ILazyQueryable interface (it returned a TModel list before).
• Export data using template (TemplateExporter)

Bug Fixes

• (Bug 3905) SqlModelMapper does not support models with “DwCompute” attribute.
• (Bug 4001) SqlExecutor.Scalar returns -1 (incorrect) if no data is found. It shall return 100.

Known Issues

• With Oracle connections, the sqlmodelmapper.Avg(string expression, params object[] parameters) does not support the return value with many numbers of decimals.
• With Oracle connections, if SqlExecutor executes a stored procedure and the return type is REF CURSOR, the cursor parameter shall be the last parameter, and the returned result-set must be single.
• With Oracle connections, it is not supported to have an array-type parameter in stored procedures.
• With ODBC (SQL Anywhere) connections, SQL batch processing is unsupported.

SnapObjects 1.0.x

What's New

These are the key features provided in SnapObjects:

• DataContext

  DataContext is the object to manage database connections and transactions.

• SqlModelMapper

  SqlModelMapper is a transaction-oriented data manipulation component compliant with .NET Standard. It can build models with data from multiple tables, support nested levels of relationships, and provide explicit and implicit transaction management for business entities (i.e. a top-level object and all of its children).

• SqlExecutor

  SqlExecutor is a set of database manipulation interfaces that have encapsulated the core components of ADO.NET. Using SqlExecutor you can directly run dynamic SQL statements, perform SQLBuilder object functions, and do model queries.

  SqlExecutor supports raw SQL as well as automatic SQL generation, supports lazy loading of data to prevent unnecessary performance bottlenecks, and can bind result-sets to POCO or dynamic models.

• SqlBuilder

  SqlBuilder constructs SQL statements in a programmatic and DB-agnostic way. With SqlBuilder you only need to build the syntax structure, and database-specific SQL statements will be generated based on the syntax structure and DataContext.

• SQL generation is controlled through a comprehensive set of model attributes:

  • For defining SQL query: FromTableAttribute; SqlJoinAttribute; SqlColumnAttribute; SqlUnionAttribute; SqlWhereAttribute; SqlParameteAttribute; SqlGroupAttribute; SqlHavingAttribute; TopAttribute
  • For Defining SQL CUD: SqlcolumnAttribute; IdentityAttribute; PropertySaveAttribute; UpdateWhereStrategyAttribute
  • For Defining master-detail relationship: ModelEmbeddedAttribute; SetValueAttribute; SqlEmbeddedAttribute

• Transactions in SnapObjects can be either explicit or implicit:

  • An explicit transaction is one that you explicitly create by using context.BeginTransaction()
  • An implicit transaction inherently includes all the CUD operations on the model until a commit method (SaveChanges in SqlModelMapper, or Execute/ExecuteProcedure in SqlExecutor) is executed.