New and Enhanced APIs in 2019 R3

Last Updated: January 2021

The 2019 R3 release of SnapDevelop provides new and enhanced APIs for SnapObjects and .NET DataStore.

New and enhanced APIs for SnapObjects

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/snapdevelop2019r3/Release_Bulletin/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/snapdevelop2019r3/Release_Bulletin/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);

New and enhanced APIs for .NET DataStore

New async methods for DataStore

The following asynchronous methods are added to the IDataStoreBase interface:

  • Task<int> UpdateAsync(bool resetFlag = true);
  • Task<int> UpdateAsync(CancellationToken cancellationToken);
  • Task<int> UpdateAsync(bool resetFlag, CancellationToken cancellationToken);
  • Task<int> UpdateAsync(UpdateSqlStrategy updateSqlStrategy, bool resetFlag = true);
  • Task<int> UpdateAsync(UpdateSqlStrategy updateSqlStrategy, CancellationToken cancellationToken);
  • Task<int> UpdateAsync(UpdateSqlStrategy updateSqlStrategy, bool resetFlag, CancellationToken cancellationToken);
  • Task<int> ReselectRowAsync(int row);
  • Task<int> ReselectRowAsync(int row, CancellationToken cancellationToken);
  • Task<int> RetrieveAsync(params object[] arguments);
  • Task<int> RetrieveAsync(object[] arguments, CancellationToken cancellationToken);
  • Task<int> RetrieveByKeyAsync(params object[] parameters);
  • Task<int> RetrieveByKeyAsync(object[] parameters, CancellationToken cancellationToken);
  • Task<int> RetrieveByPageAsync(int currentIndex, int pageSize, params object[] arguments)
  • Task<int> RetrieveByPageAsync(int currentIndex, int pageSize, object[] arguments, CancellationToken cancellationToken);

New class for importing templates

The following class is added to support importing templates (in XML/JSON format, and of Grid/Group datatype).

  • DwTemplateImporter

Support for TableBlob/InkPicture

The following attributes and datatype are added to support data retrieval and update with TableBlob/InkPicture:

  • DwTableBlobAttribute attribute for specifying the BLOB column.
  • DwInkPictureAttribute attribute for specifying the InkPic column.
  • InkPicture datatype for mapping with PowerBuilder InkPicture data.
    • Data property, corresponding to Data property in the PowerBuilder InkPicture column.
    • BackImage property, corresponding to BackImage property in the PowerBuilder InkPicture column.