Upgrading my Project to a New Version of Xtra~ Controls - It's Easy!

As I work on the help desk I occasionally talk to people who have various kinds of problems after installing updates.  I see that many customers hesitate to install updates.  Usually, they worry about two things:

•  it can break the functionality of my application which took me so long to get right!
•  most likely, it will not be easy to upgrade. I will have to waste hours on this minor update!

Yes, it sounds dangerous...  Before you make a Hamlet's decision - to update or not to update - let's estimate the risks.  I hope that after reading my blog, it will be easy for you to make such decisions.  It's easy if you know what to do.

Usually, there is a lack of information on how to carry out an upgrade.  Is it enough to install a new version or do I have to do anything special?  Publishing such information isn't given serious consideration for two reasons:

a) an upgrade is only done once;

b) information on how to update from version A to version B becomes obsolete very quickly.

Therefore, this kind of information isn't worth publishing.

Both points are quite correct, but the conclusion is a mistake.

Clear understanding of a product and the difference between its versions is a 50% guarantee of a successful update from version to version.  So please let me describe how we created our Xtra~ component set over the past 5 years.

 

As you know, we offer components for .NET Windows Forms.  They have the "Xtra" prefix in their name.  Originally there were just four products: XtraBars, XtraEditors, XtraGrid, and XtraSideBar.  However, components had something more in common than just the name prefix: they shared some code, namely, they had a common DevExpress.Utils assembly.  Thus components were interdependent and mixing their versions made the component set incompatible and lead to problems (http://www.devexpress.com/kbA675).

 

The history of XtraGrid versions

The XtraGrid is the flagship of our .NET WinForms squadron.  This does not mean however that the other controls aren't useful, they are very powerful and stable!, but the XtraGrid still has the greatest tonnage of our squadron.  It's easy to define the ages of our component suites by the version of the XtraGrid.

 

The first version of XtraGrid was created in 2001.  An installation of it was first uploaded on our Web site in April 2001.  We were the first component vendor on the .NET market with a commercial (and good, if not to say superb) product!  Well, it was not easy, but our developers had done a great job!

 

XtraGrid 1 was created when Visual Studio .NET was in beta.  There was very little information about the new .NET technology.  Microsoft's documentation on the .NET Framework in the form you see it now in appeared later.  By version 1.5.x we have significantly improved the XtraGrid 1 and made it feature rich and stable.  XtraGrid 1 was great, but it had many bottlenecks in its design. 

 

As I said, there were shared assemblies in our components.  DevExpress.Utils was used (and it is still used) by all of our .NET components.  Additionally, there were XtraEditors components.  The XtraEditors are used by many our products.  At the time of XtraGrid 1.5 the XtraEditors could be used in the XtraGrid, XtraTreeList, on toolbars and in menus of the XtraBars and as stand-alone controls on a form.  Drawbacks in the XtraEditors internal design prevented us from moving forwards.  Our developers had to make a hard decision to rewrite the XtraEditors from the ground up.  We knew that a new version would be incompatible with version 1.  But we also knew that we would never create XtraGrid 3, if we did not rewrite the XtraEditors for XtraGrid 2.

 

Upgrading a project which uses XtraGrid 1 to XtraGrid 2 is not easy.  I have written a Knowledge Base article (http://www.devexpress.com/kbA953) which covers 90% of the upgrade process from v1 to v2.  Now, as we already have XtraGrid 6.1 released, I can add just two comments to the article:

1. It's impossible to jump from XtraGrid v1 straight to v6.1.  A project with XtraGrid 1 must be first upgraded to XtraGrid 2, then to v3 and finally to v6.1.  It may sound strange, but doing so it's easier to control the upgrade process and make sure that you have your project working correctly after getting it compiled with the latest version of the XtraGrid.  This process is described in detail below in this blog.

2. The upgrade process from v1 to v2 is difficult.  If you give up performing it yourself, you can rely on our assistance in this regard.  Feel free to write to support@devexpress.com and we'll upgrade your project for you.

Here I want to thank you everyone who had their project with XtraGrid 1, converted it to XtraGrid 2 and did not lose his faith in Developer Express.  Thank you!

 

XtraGrid 2 had eight companion products: XtraBars, XtraEditors, XtraNavBar, XtraPrinting, XtraReports, XtraSideBar, XtraTreeList, and XtraVerticalGrid.  Certainly, these products were interdependent.  Customers often had a problem after updating some of these products and forgetting to update others.  We created a combined installation - Windows Forms Suite - and it prevented customers who had the entire component suite from installing incompatible versions of different components.  Customers who did not own all products still could get into trouble after installing incompatible versions.

 

There was also another problem with XtraGrid 2 - its assembly had exactly the same name as in v1.  As a result, a programmer could not have XtraGrid 1 and XtraGrid 2 installed side-by-side to work on projects with old and new XtraGrid versions (http://www.devexpress.com/kbA954).  To tell the truth, it was not a big deal: XtraGrid 2 was worth upgrading to from XtraGrid 1 regardless of the hard work involved in doing so.

XtraGrid 3 was released in April 2005.  We have learned the lesson from our customers' problems with upgrading XtraGrid v1 to v2.  XtraGrid 3 and its companion products are 99% compatible with the previous version.  The upgrade process was supposed to be smooth and it was, if compared with upgrading from v1 to v2.  We prepared an "XtraGrid v2 to v3 Conversion Guidelines" document which, unfortunately, was not published.  We also renamed the assemblies of all our .NET components - they include number 3 which indicated their compatibility with XtraGrid 3.  Users could have XtraGrid 2 (Windows Forms Suite v1) and XtraGrid 3 (Windows Forms Collection v2) installed side-by-side and quite easily detect whether an assembly belongs to XtraGrid v3 or v2 component family.  However, version numbers of different assemblies were still confusing.  For example, compatible versions are XtraGrid 3.2.3.0 and XtraNavBar 2.7.3.0 and XtraReports 1.12.3.0.  That is, one could detect compatible / incompatible versions only by the assembly build number (it's x.x.3.0 in my example) which, of course, wasn't intuitive.

 

Another problem with our XtraGrid 3 products we figured out was the Microsoft Installer engine (MSI) used in our installations.  MSI is so "clever" it "decides" itself which assemblies are interdependent and locks them in the Assembly Cache (GAC).  It happened sometimes that assemblies were not removed from the Assembly Cache after uninstalling a product.  Then after installing a new version there could be a situation when multiple versions of a given assembly were installed simultaneously.  This caused various problems both at design- and runtime.  We created a VersionChecker utility (http://www.devexpress.com/freedownloads/VersionChecker.zip) to detect these situations.  Additionally, I've written an article which should help you ensure your system is clean before installing maintenance updates to the XtraGrid v2 and v3 products (http://www.devexpress.com/kbA138).

 

DXperience 6.1 is a new generation of our .NET components product line.  The components included in the suite have been significantly updated, but, in my opinion, the fact that our new installation system solves all problems mentioned above is an even bigger step forward:

1. There is a single installation.  It will not allow you to install incompatible versions of our components.

2. All assemblies have one and the same version number.  DLL versions are no longer confusing.

3. We don't use MSI any longer.  The installation executes very fast!  The installed files aren't locked in the Assembly Cache.

4. If you decide to rebuild components from source code, it is easier to do this than before (http://www.devexpress.com/kbA609), because

* the projects' output paths are the same as the DLLs installation path;

* you can be sure that your assemblies automatically overwrite our assemblies;

* it's easy to remove the existing assemblies from the GAC - they aren't locked;

* you don't have to add any registry keys to make Visual Studio "see" your assemblies.

I hope to update the mentioned article soon if I have some spare time.

I read rumors in our public newsgroups that our new system of assembly naming is bad.  Don't worry about this and believe our experience - it has more pros than cons :-)

 

Now, as you have a notion of our products evolution, let's talk about conversion from version to version.  I will first describe the conversion process for major versions - v1 -> v2 -> v3 -> v6.1 - and then minor version updates.

 

Converter Utilities

The converter utilities - XtraConverter and ProjectConverter - are supposed to upgrade a project from a minor version of our components to a major one.  You don't need them after installing each maintenance update.

 

The XtraConverter utility (XtraConverter.exe) was shipped with XtraGrid 2.  It was intended to upgrade a project with XtraGrid 1 to XtraGrid 2.  It did the following:

1. Removed a reference to DevExpress.XtraEditors.Core from a project and added a reference to the DevExpress.Data assembly.

2. Patched the Windows Forms Designer Generated code, namely the InitializeComponent method of your forms and UserControls.

It did not patch user's code - we cannot take responsibility for changing your code.  Thus, you had to manually fix compiler errors due to any incompatibilities between the XtraGrid 1 and 2.  I mentioned this above.

 

The XtraConverter shipped with the XtraGrid 3 / Windows Forms Collection 2 and could upgrade a project with XtraGrid v2-family components to v3.  It did the following:

1. Replaced DevExpress.* references with references to the DevExpress.*3 assemblies in project files (~.csproj and ~.vbproj).

2. Cleared the content of the licenses.licx file.

Please note that this version of the XtraConverter does not change any code.  XtraGrid 3 is backwards compatible with XtraGrid 2.  After executing the XtraConverter against your project, you should be able to compile the latter without any errors.

 

Please note that the XtraConverter utilities don't support Visual Studio 2005 project files.  Thus, you should first convert your project to XtraGrid 3 and then to VS2005, not conversely.

 

DXperience 6.1 installs a ProjectConverter utility.  It does the following:

1. Replaces DevExpress.*3 references with references to DevExpress.*.v6.1 in the project files.

2. Clears the content of the licenses.licx file.

3. Parses the RESX files of your project and replaces the DevExpress.*3 references with DevExpress.*.v6.  This occurs if your project contains localizable forms.

 

General Instructions on Upgrading Your Project

I'll write my instructions in a step-by-step manner - it's easier to follow them then.  Let's consider the major upgrade process on the XtraGrid 3 to XtraGrid 6.1 conversion example.

You were using XtraGrid 3 / Windows Forms Collection 2 and have decided to install the DXperience and upgrade your project.

1. Do not uninstall XtraGrid 3.  You will do this later.

2. Install the DXperience product.

3. Backup your project.

4. Execute the ProjectConverter against the directory where your project is located.

5. Open your project (solution) in Visual Studio.  If there are forms or UserControls opened in design mode in your development environment, please close them without saving any changes.

6. Rebuild your project.  If there are compiler errors, please correct them.  Please ignore compiler warnings if any at this stage.

 

When your project is successfully built, you can open forms in design mode and carry on working on your project: launch it, test it, write new code, design forms and user controls.  If you wish to eliminate warnings introduced by the new version - some methods and properties may be marked as obsolete, please note that most of the warnings usually relate to the Windows Forms Designer Generated code.  You can easily fix them with the following steps:

7. Open a form which has warnings in design mode.

8. Change anything on this form - I advise that you change a Boolean property, e.g. set AllowDrop to true and back to false - to force re-generation of the InitializeComponent code.

9. Save your form file.

It's best to repeat steps 7-9 for each form in your project especially if your forms are localizable.  However, this is not always necessary and you don't have to do such dummy manual work :-)  Perhaps, we will work out a way to automate this process.

Instructions for a Safe Minor Update

Assume, you have DXperience 6.1.1 and want to update it to DXperience 6.1.3.  Note that you can jump to 6.1.3 without installing 6.1.2 - all our minor updates are cumulative.  Please perform the following steps:

1. Backup your project.

2. Install a new version (DXperience 6.1.3 in this case).  The installation will automatically update the previous version so you don't have to explicitly uninstall it.

3. Open your project in Visual Studio and rebuild it.  If you are using Visual Studio 2005 and get compiler errors, please see the following Knowledge Base article:

http://www.devexpress.com/kbA2950

Launch your project and check how it works.  If you have automated tests for your project, I advise that you execute them.

XtraGrid v1 to v6.1 Upgrade Walkthrough

Below are step-by-step instructions on how to upgrade a project with XtraGrid 1 to the latest version of our XtraGrid's squadron.  If, say, you have a project with XtraGrid 2, just skip the first step.

 

0. Please backup your project.  We also advise that you create a new backup after performing each step listed below.

 

1 You should uninstall the XtraGrid v.1.x components, install XtraGrid v.2 and convert your project to it.  Here is the link to the XtraGrid v.2 trial version:

http://downloads.devexpress.com/Share/Updates/WinForms1.3Trial_ToConvertGrid1to3.exe

Then please follow the instructions from this Knowledge Base article:

http://www.devexpress.com/kb953

Please note that you should use Visual Studio .NET 2002 or 2003.

 

2. Install Windows Forms Collection v.2.2.5 (contains the latest version of XtraGrid 3). 

http://downloads.devexpress.com/Share/Updates/WinForms2.2Trial_ToConvertGrid2to3.exe

Here is the document, which may help you to convert XtraGrid v.2 project to XtraGrid 3:

http://downloads.devexpress.com/Share/Updates/XtraGridV2toV3.zip

If any errors cannot be fixed, please send the error message text and the relevant code snippet.

 

3. Install DXperience 6.1 and use the ProjectConverter tool shipped with the suite to convert your project from v.3 to the latest version.

 

4. If you need to upgrade your project from VS.NET 2003 to VS 2005, please install DXperience 6.1 for Visual Studio 2005.  Convert your project to the .NET Framework 2.0 by opening it in Visual Studio .NET 2005.  I advise that you check the references to our assemblies, because they are different for .NET Framework 1.0/1.1 and .NET Framework 2.0.  The references must have a Runtime Version equal to v2.0.50727 and point to the C:\Program Files\Developer Express .NET 2005 v6.1\Sources\DevExpress.DLL directory (the default location of our assemblies).  If they don't, please delete the references and manually add them: browse to the mentioned folder and select the assemblies from it.  Finally, you will need to rebuild your project.

 

Hopefully, this information will come in handy and you will not be afraid of the upgrade process for our components.

Free DevExpress Products - Get Your Copy Today