Zen v15 ADO.NET Data Provider 4.4 and 4.5 for .NET Framework Release Notes
General Release – July 2021
Contents
The following topics provide information about Zen v15 support for both ADO.NET Data Provider 4.4 and 4.5:
•
About Zen ADO.NET Data Providers 4.4 and 4.5 for .NET Framework
•
What’s Deprecated in This Release?
•
Integrating Zen Data Tools with Visual Studio
•
Getting Started
•
Known Issues and Usage Notes
•
Technical Support
About Zen ADO.NET Data Providers 4.4 and 4.5 for .NET Framework
Zen v15 provides two versions of the ADO.NET data providers: 4.4 and 4.5. All versions are installed by default with the database engine. For more information about compatibility and how to use the providers, see Zen Data Providers for .NET Guide. This guide is included in the \doc directory of the SDK download. For further information about developing .NET applications, see Zen Programmer’s Guide in the Zen developer documentation.
What’s Deprecated in This Release?
The integration of data tools, project templates, item templates, and Entity Framework model-first templates into Visual Studio as described in this documentation is no longer supported for versions of Microsoft Visual Studio before to Visual Studio 2017.
Integrating Zen Data Tools with Visual Studio
Zen ADO.NET data provider SDK packages are available for download from the Actian website. They contain design-time files (documentation and code samples) as well as provide Visual Studio integration of Zen ADO.NET data provider templates and data tools. Each supported version of the Zen ADO.NET Data Provider has a separate download.
4.4 and 4.5 Provider SDKs
The download for the 4.4 or 4.5 data provider for .NET SDK is an archive file in .zip format. After you manually extract the package on the target system, you will find the following things:
•
Documentation
•
Coding samples
•
PowerShell script for integrating the templates and data tools
Instructions for integrating these items with Visual Studio are given in the next section.
Integration with Visual Studio
Zen ADO.NET Data Provider 4.4 and 4.5 SDKs provide integration of the Zen ADO.NET data provider templates and data tools with Microsoft Visual Studio 2017 and 2019.
To integrate the templates and data tools into Visual Studio, we recommend using the PowerShell installation script provided in the VisualStudioDataTools directory in the archive file.
The PowerShell script handles installing one of the Visual Studio Extensions (VSIX) packages provided in the same directory in the archive file, which integrates the Zen project and item templates and the Zen data tools into Visual Studio. Since VSIX packages do not currently support integrating Entity Framework model-first templates, the PowerShell script also copies the Zen model-first templates from their location in the package to the appropriate VS directory so long as VS is configured for Entity Framework development.
Integration Using PowerShell
To use the PowerShell installation script, you must have PowerShell 3.0 or later installed and configured with the execution policy set to allow the running of signed scripts. You also must run the PowerShell session with elevated permissions.
►
To run the PowerShell script
1
Extract the contents of the archive .zip package to a location on the target system.
2
Start a PowerShell session using the Run as Administrator option.
3
At the PowerShell prompt, execute the following:
PS> <path_to_script>\Load-PSQL-DataTools.ps1 install
►
To remove the integration with VS after using PowerShell
1
Repeat steps 1–2 in the previous task.
2
At the PowerShell prompt, execute the following:
PS> <path_to_script>\Load-PSQL-DataTools.ps1 remove
Integration Using a VSIX Package (Without the Model-First Templates)
If you do not need the Zen model-first templates for Entity Framework development, the VSIX packages can be installed directly using the Visual Studio utility VSIXInstaller.exe.
►
To install a VSIX package directly
1
Extract the contents of the archive .zip package to a location on the target system.
2
In Windows Explorer, in the target system location, browse to the VisualStudioDataTools directory.
3
To launch the VSIX installer, double-click the following VSIX package:
Zen.VisualStudio.DataTools_2017_2019.vsix for VS 2017 through 2019
4
Follow the instructions in the VSIX installer wizard.
►
To remove the integration with VS after a direct installation
1
Start VS and select Tools > Extensions and Updates.
2
Locate the installed package Pervasive DataTools.
3
Click the Uninstall option and follow the instructions in the VSIXInstaller utility uninstallation wizard.
Getting Started
The files required for the Zen ADO.NET data providers are made available in different ways:
•
Most of the provider assemblies are included by default when the Zen database engine (all editions) is installed.
•
Design-time files, sample source code, templates, libraries, and the Zen Membership Provider for ASP.NET 2.0 are included in the SDK.
Provider Assemblies
Installation of the database engine copies all provider assemblies to version-specific directories under the Zen\bin directory in the Zen installation location. Separate directories are used for 4.4 and 4.5, each with a separate subdirectory for the Entity Framework provider assembly. The only exception to this layout is the Membership Provider for ASP.NET 2.0, which is described under Membership Provider for ASP.NET 2.0.
If the Zen database installation detects a supported version of the .NET Framework, the following also occurs:
•
The provider assemblies are installed to the Windows Global Assembly Cache (GAC) as assembly versions 4.4.0.0 and 4.5.0.0.
•
The .NET Framework DbProviderFactories namespace is updated with the following Provider instances:
•
Pervasive.Data.SqlClient.4.5
•
Pervasive.Data.SqlClient.4.4
•
Pervasive.Data.SqlClient
Note The instances are added to the DbProviderFactories namespace only for final, general availability (GA) releases of the .NET Framework. The namespace is not updated if the .NET Framework installed on the system is a release prior to GA, such as alpha, beta or release candidate (RC).
The generic provider instance (Pervasive.Data.SqlClient) always points to the latest provider assembly.
The provider assemblies copied to the Zen\bin directory are not precompiled at installation time. That is, they are not added to the Windows native image service on the local computer. If you include the provider assemblies as private, side-by-side assemblies installed with your application and want them added to the Windows native image service on the target system, your installation must add them. For more information, see the Native Image Generator topic in the Microsoft MSDN Library.
Referencing the Different Providers
In addition to installing the sample source code files, templates, and libraries, the SDK installer also performs the following integration for the Zen ADO.NET data providers:
•
Versions 4.4 and 4.5 of the provider integrate with Visual Studio 2017 and 2019.
•
Integrates the provider with Windows Performance Monitor (perfmon).
•
Integrates the provider with Visual Studio Server Explorer.
•
Adds a Tools menu option in Visual Studio: Pervasive > Pervasive Performance Tuning Wizard.
•
Adds Item and Project templates for both Visual C# and Visual Basic to the Visual Studio IDE. If Visual Studio is configured for Entity Framework development, then additional ModelFirst templates are copied to the appropriate Visual Studio installation directory.
Installing Visual Studio After Installing the Zen ADO.NET Data Provider
If you install Visual Studio after installing the Zen ADO.NET SDK, rerun the integration steps given above.
Logging Application Block Configuration
For the Logging Application Block to function correctly, you must include the following line in your application:
ConfigurationManager.GetSection("Pervasive.Data.SqlClient.Entity");
Design Considerations
The following information can help you decide how you want to design your application to function with the Zen ADO.NET data providers for .NET Framework.
Design Method
Comments
Application references generic provider instance of Zen Provider
•
Application can use updates to the provider without being recompiled.
•
Application does not need to distribute the provider files.
•
Application always uses the latest assembly version installed in the GAC by the Zen installation and updated by Zen patches.
Application references a version-specific provider instance such as Zen ADO.NET Data Provider 4.4.
•
Application always uses the latest patches for a particular version of the provider installed in the GAC.
•
Application will not use new releases of the provider installed by Zen.
Application references the provider’s strong name. The strong name consists of an assembly's text name, version number, and culture information (if provided), with a public key and a digital signature generated over the assembly.
•
Application distributes that specific version of the provider.
•
Application installs the specific provider as a private side-by-side assembly in the application installation directory.
Membership Provider for ASP.NET 2.0
The ASP.NET login controls use the custom Zen Membership Provider to specify a separate database for storing user information.
The Microsoft MSDN Library provides additional information about writing a custom membership provider. See the Assembly topic for the location of the Membership Provider.
The sample ASP.NET application included with the libraries and samples shows how to create users, change passwords, recover passwords, and validate users.
Assembly
The Zen Membership Provider assembly, named PSQL.Membership.Provider.dll, is not installed by default with the Zen database. This provider assembly is contained in the Zen ADO.NET SDK. For the Zen ADO.NET SDK, the membership provider is stored in a .zip archive in the same folder location (samples\MembershipProvider\bin).
Membership Provider Requirements
•
PSQL.Membership.Provider.dll
•
Database using V2 metadata and a table of user information. The table also must be defined with V2 metadata.
►
To use the Membership Provider
1
Create the Zen database using V2 metadata.
2
Create a table using Users Table SQL Script.
3
Modify the membership section in the web.config file. For reference, see Example Modified Web.config File.
After you complete these steps, login controls within ASP.NET can use the Zen Membership Provider.
Users Table SQL Script
CREATE TABLE Users
(
 PKID UniqueIdentifier NOT NULL PRIMARY KEY,
  Username Char (255) NOT NULL,
  ApplicationName char (255) NOT NULL,
  Email Char (128) NOT NULL,
  Comment Char (255),
  "Password" Char (128) NOT NULL,
  PasswordQuestion Char (255),
  PasswordAnswer Char (255),
  IsApproved SmallInt,
  LastActivityDate DateTime,
  LastLoginDate DateTime,
  LastPasswordChangedDate DateTime,
  CreationDate DateTime,
  IsOnLine SmallInt,
  IsLockedOut SmallInt,
  LastLockedOutDate DateTime,
  FailedPasswordAttemptCount Integer,
  FailedPasswordAttemptWindowStart DateTime,
  FailedPasswordAnswerAttemptCount Integer,
  FailedPasswordAnswerAttemptWindowStart DateTime
)
Example Modified Web.config File
<connectionStrings>
<add name="PsqlServices" connectionString="ServerDSN=ASPNETPSQL;" /> </connectionStrings> <system.web>
<membership defaultProvider="PsqlMembershipProvider" userIsOnlineTimeWindow="120">
<providers>
<clear />
<add
name="PsqlMembershipProvider"
type="PSQL.Membership.PsqlMembershipProvider"
connectionStringName="PsqlServices"
enablePasswordRetrieval="true"
enablePasswordReset="true"
requiresQuestionAndAnswer="true"
writeExceptionsToEventLog="true"
debug="false"
passwordFormat="Clear"/>
</providers>
</membership>
</system.web>
IPv6 Environment
The Zen ADO.NET Data Provider for .NET Framework supports IPv6 environments, either IPv4/IPv6 mixed or IPv6-only.
Documentation
Zen Data Providers for ADO.NET Guide to Application Development is included in the \doc directory of the SDK download. For further information about developing .NET applications, see Zen Programmer’s Guide in the Zen developer documentation.
Samples
The following table summarizes the samples provided with the ADO.NET data providers for .NET Framework. The sample files are located in the samples folder of the SDK .zip archive.
 
Directory
Sample
Purpose of Sample
Provider
CommandBuilder
Creating a command from an SQL statement
CreateDatabaseObjects
Creating database objects such as a table or stored procedure
DataAdapter
Using the data adapter to read or modify data
DataGridUpdate
Updating data in a grid control
DataReader
Using the data reader to get data
Escapes
Processing escape functions in statements
LimitingRows
Limiting the number of rows returned in a result set
LocalTransactions
Processing a transaction
LongDataTypes
Using long data types such as LONGVARCHAR
ScalarValue
Executing scalar functions to return a value
StoredProcedures
Using stored procedures
MembershipProvider
ASPX files for using the membership provider with the ASP.NET login controls
Various login activities, changing password, and so forth
Enterprise Library
Sample using Microsoft Enterprise Library
Demonstrating the use of Microsoft Enterprise Library
Known Issues and Usage Notes
The Actian community forums and knowledge base both enable you to search for a history log that lists issues fixed and enhancements added since the previous release. You can also find a list of general known issues in addition to those specifically listed here.
•
VS Integration using VSIX package requires an Internet connection
Zen ADO.NET SDK integration with Visual Studio using the VSIX package needs an Internet connection to validate the certificate of the authority that has signed the package.
•
VS 2017 Error Message “The <DataPackage> package did not load correctly.”
If the .NET Desktop Development workload is not installed for Visual Studio 2017, then after the Zen ADO.NET Provider data tools are integrated this error message appears when the user selects the option Run Pervasive Performance Tuning Wizard from the Tools > Pervasive menu. The issue can be fixed by rerunning the Visual Studio 2017 installation and selecting the .NET Desktop Development workload for installation and then rerunning the PowerShell script to integrate the Zen ADO.NET Provider data tools, or by reinstalling the VSIX package.
•
Entity Framework Applications Upgrade from EF5 to EF6 – Code First
While working with Entity Framework applications, upgrading from Microsoft ADO.NET Entity Framework v5.0 (EF5) to v6.0 (EF6) against the same database may cause issues in the Code First workflows. Thereby you receive NotSupported exception. To resolve, drop the __MigrationHistory table and then rerun the application.
•
Code First Migration – Map to Stored Procedure
In the Code First Migration workflow, with the stored procedure mappings enabled, running the Enable-Migration command creates a <Timestamp>_InitialCreate.cs file in the Configuration folder, which causes build errors.
To resolve this issue, delete <Timestamp>_InitialCreate.cs. Its deletion has no effect on data loss or migrations.
•
Code First Migration – On Tables Containing Data
Performing Code First migrations on a table that contains data in the back end returns a "File is locked" error. This is because in the Code First migration workflow of Entity Framework, all queries are executed inside a local transaction (generally Alter Commands). This behavior is not supported by Zen.
•
Code First – Set Initalizers
When two or more Entity applications try to connect to same database, where at least one context contains set initializers other than "Create Database If Not Exist," data may be lost. To resolve this issue, you can use the customizable Migration History feature and give the new Migration History table a different name from the existing table in the back end.
•
Customizing the Migrations History Table – Renaming __MigrationHistory table
While renaming the __MigrationHistory table, be sure that the HistroyContext primary key length is within the 254-byte maximum length allowed by Zen.
•
Customizing the Migrations History Table – Resizing Key Column Lengths
For Code First migrations, when you resize the default primary key columns of the customizable Migration History table, you must adhere to the maximum allowed primary key length set by the Zen server. Otherwise, the provider sets the default length values as follows:
If Unicode is enabled, then lengths are as follows:
•
MigrationId is 42.
•
ContextKey is 83.
If Unicode is not enabled, then lengths are as follows:
•
MigrationId is 85.
•
ContextKey is 169.
•
Customizing the Migrations History Table – Renaming Migration History Table
For a Code First model, renaming the Migration History table may cause issues while working with DropCreateDatabaseIfModelChanges or DropCreateDatabaseAlways Set Initializers.
Progress recommends that you rename the Migration History table at another time.
•
Customizing the Migrations History Table – Adding New Columns
Due to third-party limitations, you cannot modify the size of any column after adding new columns to the customizable Migration History table.
•
Code First Migration – Add/Drop Multiple Columns or Alter Column to Contexts with Relationships
Adding multiple columns or dropping multiple columns or altering single or multiple columns in a single migration, where the context has relationships, results in Btrieve error 88. This is a known issue for Zen.
•
Lightswitch 2011 and 2012 Support
Lightswitch loads the DateTime control for the Zen Date column. When you load a table with a Date type column to be used in a Lightswitch application, Lightswitch loads the DateTime control for it. Since storing of time values is not supported, the time entered for the field is not preserved and the application resets the time portion to 00:00. As a workaround, change the Lightswitch mapping for this column in the Lightswitch designer to Date instead of DateTime.
•
Entity Framework Support
The Entity Framework provider does not support mapping for UniqueIdentifier type. When you choose a table that contains a column of type UniqueIdentifier while generating an entity data model, it returns the error "UniqueIdentifier data type is not supported." The table is still imported in the entity model but, without the column of type UniqueIdentifier. You can continue to work with this table in an Entity Framework application if the column of type UniqueIdentifier is nullable.
•
Installing on a Machine with Earlier Versions of the Data Providers
Zen ADO.NET Data Provider 4.4 and 4.5 for .NET Framework can exist on the same machine with earlier released versions of the data provider, including the GA version or any of the patches or service packs. However, it cannot be installed in the same directory.
•
Zen ADO.NET Data Provider for .NET Framework Missing from Perfmon List
If you do not find the installed ADO.NET data provider listed in the Performance Object list of perfmon, do the following:
•
Confirm that the data provider was installed with Administrator rights.
•
Run the .NET application that references the ADO.NET data provider.
The data provider should then be available in the list.
•
Logging Application Block Configuration
In order for the Logging Application Block to function correctly, you must include the following line in your application:
ConfigurationManager.GetSection("Pervasive.Data.SqlClient.Entity");
•
Installing Visual Studio After Installing Zen ADO.NET Data Providers for .NET Framework
To install Visual Studio for the first time on a machine that has a Zen ADO.NET data provider for .NET Framework installed, you must use the Visual Studio Integration Tool.
•
To install the Visual Studio Integration Tool
At a command prompt, run the InstallProviderIntegration.cmd script, located in the Tools directory. Specify the installation directory of the Pervasive.Data.SqlClient.dll.
•
To uninstall the Visual Studio Integration Tool
At a command prompt, run the UninstallProviderIntegration.cmd script, located in the Tools directory.
Technical Support
You can find information and obtain help at the Actian website:
•
To join a community forum discussion or search for knowledge base topics, visit the Actian Community and Customer Portal and select Actian Zen from the Products menu.
•
To log a support case or purchase support services, visit Actian Support and Services and select an option from the Support menu.
Disclaimer
ACTIAN CORPORATION LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN "AS IS" BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE AGREEMENT.
Copyright © 2021 Actian Corporation. All Rights Reserved.