VistaDB 5
Gibraltar VistaDB > Developer's Guide > ADO.NET Overview > ADO.NET Factory Objects in your app.config or web.config
ADO.NET Factory Objects in your app.config or web.config

Background on Factory Objects

VistaDB supports the ADO.NET Factory classes to allow you the ability to dynamically load the provider at runtime based upon your connection string. This is a very nice concept, but is has some complexity over using normal methods, and a few quirks when you go to ship your application.

If you are looking for the way to avoid using SqlClient in your code directly (or VistaDBClient) and want to just load the correct DbFactory this is the correct way to do it.

Example App.config and Web.config

This is an example app.config that is placed in the directory with your application. It must be named the same name as your exe with a .config appended on the end. So an application names ParentConsumerApp.exe must have a config file of ParentConsumerApp.exe.config or it will not load correctly. These entries below in that config file are easily loaded by the code below.

Web.config is identical, but only placed on the root of your website.

App.Config with VistaDB Provider Factory
Copy Code
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="YourAppConnection" 
         connectionString="Data Source='|DataDirectory|\Database.vdb5'" 
         providerName="System.Data.VistaDB5" />
  </connectionStrings>
  <system.data>
    <DbProviderFactories>
      <remove invariant="System.Data.VistaDB5" />
      <add invariant="System.Data.VistaDB5" name="VistaDB 5 Data Provider" 
           description="VistaDB 5 ADO.NET Provider for .Net"
            type="VistaDB.Provider.VistaDBProviderFactory, VistaDB.5.NET40" />
    </DbProviderFactories>
  </system.data>
</configuration>

The connection string in the example above specifies a providerName of "System.Data.VistaDB5".  This is then resolved in the list of DbProviderFactories by looking for an entry with a matching "invariant" name.  When it finds a match it will then load the type specified by the provider factory and ask it to create all of the various objects it needs for data access.

If you are using VistaDB.5.NET40 (recommended for .NET 4.0 and later applications) use this DbProviderFactory setting:

<add invariant="System.Data.VistaDB5" name="VistaDB 5 Data Provider" 
      type="VistaDB.Provider.VistaDBProviderFactory, VistaDB.5.NET40" />

If you are using VistaDB.5.NET20 (for supporting .NET 2.0 - .NET 3.5 applications) use this DbProviderFactory setting:

<add invariant="System.Data.VistaDB5" name="VistaDB 5 Data Provider" 
      type="VistaDB.Provider.VistaDBProviderFactory, VistaDB.5.NET20" />

Using VistaDB Through the ADO.NET Factory

The following code sample shows how to use VistaDB through the ADO.NET factory.  The great benefit of this approach is that you can use VistaDB or SQL Server without changing any of this code - both support the ADO.NET factory so simply changing the provider invariant name in the connection string will switch the database engine being used.

Using VistaDB Strictly through Provider Example
Copy Code
public static bool TestVistaDB(out string VersionInfo)
{
 for( int i=0; i< System.Configuration.ConfigurationManager.ConnectionStrings.Count; i++ )
    {
        System.Diagnostics.Debug.WriteLine(System.Configuration.ConfigurationManager.ConnectionStrings[i].ToString());
    }
 
    string connectionName = "myVDBConnection";
    // Find this connection string in the app.config
    System.Configuration.ConnectionStringSettings connectionString = System.Configuration.ConfigurationManager.ConnectionStrings[connectionName];
    if( connectionString == null )
    {
        VersionInfo = "Failed to load connectionString from config file";
        return (false);
    }
    // Loads the factory
    System.Data.Common.DbProviderFactory factory = System.Data.Common.DbProviderFactories.GetFactory(connectionString.ProviderName);
    // After this it looks pretty normal
    using (DbConnection connection = factory.CreateConnection())
    {
        connection.ConnectionString = connectionString.ConnectionString;
        connection.Open();
        using (DbCommand command = connection.CreateCommand())
        {
            command.CommandText = "SELECT @@VERSION;";
            command.CommandType = CommandType.Text;
 
            using (DbDataReader reader = command.ExecuteReader())
            {
                while (reader.Read())
                {
                    string result = reader.GetString(0);
                    if (!reader.IsDBNull(0))
                    {
                        VersionInfo = result;
                        return (true);
                    }
                }
            }
        }
    }
    VersionInfo = string.Empty;
    return (false);
}

Deployment

When you deploy your application that uses VistaDB you'll need to be sure the VistaDB engine is deployed at the same time. It should be simply copied into the same directory as your application binaries.  We do not recommend placing VistaDB assemblies in the Global Assembly Cache (GAC) unless it is absolutely required (say because you're developing a Visual Studio AddIn) since the assembly version is changed infrequently and you will cause any other application on the deployed system to use your specific version of VistaDB.

Sample App

Download the sample factory client using provider factories written in C# and look how it work (download from our blog, or look in your samples directory). If you rename or remove the .config file from the parent you will see the error message.

Entity Framework Distribution

In order to distribute your application built with the Entity Framework you must also include an App.config or put the provider factory into the GAC on the target machine. Deploying your EF powered application will result in an error on the target machine otherwise:

The specified store provider cannot be found in the configuration, or is not valid. 

This is because the Entity Framework only loads from provider factories.  It doesn't matter if you hard code the assembly reference in your app, on the target runtime machine your application has to be able to find the factory.


See Also