How to maintain compatibility for GXextensions

Being a live product, GeneXus is constantly growing and evolving. Most of the time, changes add new features or fix some problems, taking extra care that existing extensions keep working even if they are not recompiled with the new libraries. This of course is not always possible. Sometimes, a parameter in a method needs to change its type, or some method disappears, or the extensions are required to call some new method, or... well, you get the idea: a breaking change was born.

How can GeneXus know whether it should load and use a particular extension, or whether it should better avoid even trying to load it? This is where the PackageCompatibility attribute comes in handy.

namespace Artech.Architecture.Common.Packages

{

   public sealed class PackageCompatibilityAttribute : Attribute

   {

      private int version;

 

      public int Version

      {

         get { return version; }

         set { version = value; }

      }

   }

}

This is how this attribute is used:

using Artech.Architecture.Common.Packages;

 

[assembly: PackageCompatibility(Version = 1)]

The PackageCompatibility attribute is used both in GeneXus and in every extension. It contains a single property used as a version number. Each time GeneXus starts, when it's about to load an extension, it first checks its internal version number with that present in the extension. If the numbers match, everything goes as expected; otherwise, the extension is not loaded.

Every time a breaking change is introduced, GeneXus will increment its PackageCompatibility version number. This way, only those extensions that are updated to that version number will be loaded.

How to maintain compatibility

The easiest way to maintain an extension compatible with successive versions of GeneXus is having a link in your extension's project to CommonPackageInfo.cs in GXextensions SDK installation.

Use Project / Add Existing Item (Shift+Alt+A) to invoke the file selector dialog, locate CommonPackageInfo.cs in the Src folder of the SDK (eg: "C:\Program Files\ARTech\GeneXus X Platform SDK\Src\CommonPackageInfo.cs"), click on the litle triangle to the right of the Add button, and select "Add As Link". This way, all your extension projects can share this file, which will be updated every time you install a new SDK version.

Link to CommonPackageInfo

Whenever you need to update your extension, all you need to do is build the project after updating the SDK. Of course you'll need to take care of possible compilation errors, and check the documentation for other changes you may need to do in your source files, but the version number in the PackageCompatibility attribute will already be updated.