VistaDB 6
VistaDB / Getting Started / Getting Started - Upgrading to VistaDB 6
In This Topic
    Getting Started - Upgrading to VistaDB 6
    In This Topic

    If you're using VistaDB 3.x through 5.x, just walk through the following items to upgrade your application to VistaDB 6. 

    .NET Framework 4.5.1 or Later Required:  VistaDB 6 does not support versions of .NET older than 4.5.1.  You will need to first upgrade your application to target .NET Framework 4.5.1 or later before upgrading to VistaDB 6.
     Step 1: Change References

    You will need to remove references in your application to the older VistaDB libraries and replace them with the appropriate updated reference:

    If You Referenced... Replace it with...

    VistaDB.NET20.dll
    or
    VistaDB.4.dll
    or
    VistaDB.5.NET20.dll
    or
    VistaDB.5.NET40.dll

    NuGet package VistaDB.6
    VistaDB.Entity.4.dll
    or
    VistaDB.5.Entities.4.0.NET40.dll
    NuGet package VistaDB.6.Entities.4

    Upgrade Packages

    If you are using one of the VistaDB NuGet packages you'll need to remove it and switch to the package that targets VistaDB 6.

    If You Referenced... Replace it with...

    VistaDB.5.Entity.4

    VistaDB.6.Entity.4
    VistaDB.5.Entity.6 VistaDB.6.Entity.6
    VistaDB.5.Loupe VistaDB.6.Loupe

    At this point your project may not compile if you are using Typed DataSets or have certain application configuration entries.

    Upgrading Entity Framework

    The Entity Framework EDMX file contains an explicit reference to the EF Provider that the EDMX file was generated with.  This will need to be updated to switch from an older version of VistaDB to a newer version.  To do this, open the EDMX file using the XML editor and then change any reference to System.Data.VistaDB4 or System.Data.VistaDB5 to System.Data.VistaDB6.

    To open the EDMX file in an XML editor right-click on the EDMX file and select Open With... and then XML (Text) Editor

    If you have been using Entity Framework you are likely planning two upgrades - one for Entity Framework and one for VistaDB.  We recommend you first upgrade VistaDB to VistaDB 6 while keeping Entity Framework the same and then upgrade to Entity Framework 6 (or later) following our guide to Using VistaDB with Entity Framework - Upgrading To Entity Framework 6.  Here is an example start of an EDMX file where the Provider has been updated to System.Data.VistaDB6 and the ProviderManifestToken set to 6.0.

    <?xml version="1.0" encoding="utf-8"?>
    <edmx:Edmx Version="3.0" xmlns:edmx="http://schemas.microsoft.com/ado/2009/11/edmx">
      <!-- EF Runtime content -->
      <edmx:Runtime>
        <!-- SSDL content -->
        <edmx:StorageModels>
          <Schema Namespace="PrimaryModel.Store" Provider="System.Data.VistaDB6" ProviderManifestToken="6.0"
                  Alias="Self" xmlns:store="http://schemas.microsoft.com/ado/2007/12/edm/EntityStoreSchemaGenerator"
                  xmlns:customannotation="http://schemas.microsoft.com/ado/2013/11/edm/customannotation"
                  xmlns="http://schemas.microsoft.com/ado/2009/11/edm/ssdl">
    

    Updating Typed DataSets

    If you previously used the Visual Studio DataSet designer to create DataSets for your data access using VistaDB 5 or earlier you will need to edit them using the Xml editor in Visual Studio to update their reference.  For details see How To - Update Datasets to use VistaDB 6.

     Step 2: Changing Connection Strings and Application Configuration

    Your application or web site should have a configuration file entry for the VistaDB data provider.  You'll need to update this to point to the new assembly so that ADO.NET can find it at runtime.  You can generally search for any reference to "VistaDB.5.NET40", "VistaDB.4" or "VistaDB.NET20" (depending on the version you're upgrading from) and change the assembly name to the assembly you selected in Step 1.  In the end you want it to look like this:

    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
      <connectionStrings>
        <add name="YourAppConnection" 
             connectionString="Data Source=YourAppDatabase.vdb6;Open Mode=SingleProcessReadWrite" 
             providerName="System.Data.VistaDB6" />
      </connectionStrings>
      <system.data>
        <DbProviderFactories>
          <remove invariant="System.Data.VistaDB6" />
          <add invariant="System.Data.VistaDB6" name="VistaDB 6 Data Provider"
               type="VistaDB.Provider.VistaDBProviderFactory, VistaDB.6" />
        </DbProviderFactories>
      </system.data>
    </configuration>
    

    The most important change is in the line that adds the new DbProviderFactory - the type needs to be set to refer to the new engine assembly.

    <add invariant="System.Data.VistaDB6" name="VistaDB 6 Data Provider" 
          type="VistaDB.Provider.VistaDBProviderFactory, VistaDB.6" />
    
           

    In the above example the provider name is set to the default used for VistaDB 6 (System.Data.VistaDB6) but this can be anything in your application as long as you use the same value in the connection string and in the DbProviderFactories invariant name.

    Why does the configuration example first remove the provider factory? On any computer where VistaDB 6 has been installed the provider factory is already registered in the machine.config file so it will be present.  This is necessary for the VistaDB Visual Studio designer to work but isn't a recommended deployment configuration.  Therefore, the system-wide setting has to be removed for your application to add its own setting.  Otherwise your application will fail on your development box (but will work when deployed)
           

    For more information on how to configure your connection in your application configuration file, see ADO.NET Factory Objects in your app.config or web.config.

     Step 3: Upgrading your Database

    VistaDB 6 has a new database file format compared to older versions of VistaDB.  While the VistaDB 6 engine can continue to read older formats, the database will need to upgraded to the VistaDB 6 format to be written to.  Upgrading a database is as simple as packing it using either the API or Data Builder.  If your database is using the .vdb5 extension (the default) for VistaDB 5 then you'll want to rename it to .vdb6 as well so double-clicking it will open Data Builder. 

    If you have your database in your Visual Studio project we recommend renaming it to change the file extension then double-clicking it to open it in Data Builder.  You can then upgrade it from Data Builder.

    Be sure to update your connection string and other places you reference the file extension in your application

     Step 4: Deploying Your Upgrade

    When deploying your updated application, you will need to handle upgrading the deployed database.  The best way to do this is to use the VistaDB API to Pack the database.   You may want to follow a process similar to this:

    1. Detect an old database by checking that the data file has the extension .vdb5 and there isn't a corresponding file with the extension .vdb6
    2. Upgrade the database using the Pack API.  Rename the database file after the Pack has successfully completed.  This is a good scenario to use the backup option where a backup copy is made during the upgrade.  For more information, see How To - Pack a Database.
    3. Update the stored connection information to refer to the new file name with the new extension
    See Also