My company uses ASNA Visual RPG (AVR) 10.2 with Visual Studio 2010 and WebPak 10.2. What is the path to upgrade to the latest versions of this software--and what issues should we expect?
ASNA supports the current version of a given product and one version back. As of April 2021, the current version of AVR for .NET is 16.x and it uses Visual Studio 2019. Anytime you're using a retired version we strongly recommend upgrading to a supported version.
"Supports" means that the product is tested on its supported platforms and gets updates and fixes. When an ASNA product is retired it is no longer tested and no longer receives any updates. See the list of current ASNA products and their supported platforms and the list of retired ASNA products and their supported platforms
This guide applies to any version of AVR for .NET from AVR for .NET 8.x and up. If you need to upgrade AVR for .NET 7.x (the first version of Visual RPG for .NET) applications please contact ASNA tech support for information on that upgrade. Microsoft introduced many .NET Framework changes that make AVR for .NET 7.x upgrades substantially more challenging than upgrading any other version of AVR for .NET.
Don't be put off by the amount of text provided here. Upgrading is actually a pretty simple process. Some customers, though, may need more details than others. If you are very familiar with ASNA products, you can skip ahead to the "On with the upgrade" subhead.
In many upgrades for AVR for .NET products are included as a part of your ASNA maintenance plan. Please check with your ASNA sales representative to see if you qualify for a free upgrade.
Downloading products to install
The ASNA products you need to perform an AVR for .NET upgrade are all available for download at asna.com. See this article for how to create an asna.com account so that you can download products. (Don't forget to read the release notes, if available, for product downloads.)
AVR runtime frameworks
AVR for .NET produces binary .NET assemblies (executables). These client executables are supported at runtime by one of two ASNA server products:
For AVR for .NET ASP.NET Web applications, ASNA DataGate WebPak provides AVR for .NET Web application runtime support. WebPak must be installed on any Web server on which you want to run AVR for .NET binaries for ASP.NET apps.
For Windows fat clients, ASNA AVR for .NET Windows Deployment provides AVR for .NET fat client runtime support. Windows Deployment must be installed on any PC on which you want to run AVR for .NET fat client binaries.
Do not install the AVR for .NET Windows Deployment on a developer PC. The AVR for .NET install includes the development runtime.
To perform an AVR for .NET upgrade, you'll need to update both developer PCs and your production servers/PCs. You may also need to upgrade DataGate for the IBM i or DataGate for SQL Server.
Different versions of AVR for .NET and its runtimes cannot coexist on the same PC or server. There can only be one version of AVR for .NET installed on a developer PC and only one version of either WebPak or Windows Deployment on a given PC or server. If you need to have your old version available, consider setting up a virtual machine with your older software on it for that purpose.
WebPak/Windows Deployments are backwards compatible
AVR for .NET produces a versioned executable; for example, AVR for .NET 10.2 produces a version 10.2 executable. AVR executables run under a version of either WebPak or Windows Deployment that is versioned either equal to or higher than the AVR version. In other words, WebPak/Windows Deployment 16.x is backwards compatible with equal or lower AVR clients. For example, an AVR 10.2 executable works with WebPak/Windows Deployment versions 10.2 and higher. However, a higher AVR client assembly does not work with a lower server version. An AVR 16.x executable would not work with WebPak 12x.
Lower version clients work with higher version database components. That is AVR 12.x does connect to DataGate for IBM i or WebPak 16.x. However, AVR 16.x will connect only to DataGate for IBM i or WebPak 16.x or higher.
This backward support for WebPak/Windows Deployment means that you usually don't have to recompile AVR executables with a higher level of AVR when you upgrade to a newer version of WebPak/Windows Deployment. That said...
The fidelity of an AVR executable's forward compatibility may be affected by the age of your AVR executables. WebPak 16.x was produced in 2020; AVR 14.x in 2018; and AVR 10.x in 2013. Much older executables may have issues running under much newer WebPak/Windows Deployment versions. For example, an AVR 14.x executable should have no issue running under WebPak 16.x. However, an AVR 10.x executable has the potential to have problems running under WebPak 16.x. (These problems would generally be resolved by recompiling the project to convert its executable to version 16.x and then redeploying the executable.)
We recommend keeping your production executable versions within three versions of your WebPak/Windows Deployment version.
Before you do anything else, backup all of your 10.x projects!
Make a good backup of your current 10.x projects. Opening a 10.x project with AVR for .NET 16.x performs an implicit one-way conversion of the project to 16.x. This conversion can't be undone. If you need to roll the upgrade back, you'll want to have this backup available. Remember, too, that source control isn't backup! It's very important to have a good, byte-for-byte project backup in the rare case where you might need to roll an upgrade back.
Read our release notes
Most ASNA product downloads have release notes! Please read these carefully for each product you need before attempting to install anything. For example, the AVR for .NET 16.x release notes explain a runtime references change that you might need to make to your older projects.
Confirm IBM i and/or SQL Server compatibilities
Use the ASNA Version Policy page to ensure that your IBM i OS version and DataGate for IBM i version are compatible with your upgrade. For example, the Version Policy page shows that AVR for .NET 16.x requires DataGate 16.x and that DataGate 16.x requires IBM i V7R2 or higher.
If you need to upgrade DataGate for IBM i, we recommend you do that before you do anything else. Installation instructions are available here. See this link for how to determine what version of DataGate for IBM i you are currently using.
If you need to upgrade DataGate for SQL Server, we recommend you do that before you do anything else. Installation instructions are available here. See this link for how to determine what version of DataGate for SQL Server you are currently using.
DataGate for IBM i and DataGate for SQL Server are both backwards compatible with WebPak/Windows Deployment versions. For example, DataGate for IBM i 16.x is compatible with WebPak 14.x.
Testing is very important
The last item on the upgrade list (presented below) is to test your applications thoroughly after having installed your upgrade. We strongly recommend that before installing any upgrades on a production server, you first install things on a test server or test PC and test all applications thoroughly there before attempting the upgrade on a production box. Nearly all upgrades go quite smoothly, but Murphy lurks!
On with the upgrade
Enough back story! Let's get on with the upgrade.
For developer PCs
- Acquire Visual Studio 2019 for your developers. Microsoft used to offer a free Visual Studio "shell" into which AVR could be installed. Microsoft has since discontinued these shells. It also used to be that AVR could be installed into the Visual Studio Community Edition. That is also no longer the case--Microsoft changed how the Community Edition supports third-party products (perhaps to limit the unlicensed use of the Community Edition in the enterprise). You need a commercial version of Visual Studio 2019 Professional or Enterprise.
Unlike AVR for .NET, you can have multiple versions of Visual Studio on a single PC. However, unless you have a compelling need to keep your old version of Visual Studio, we recommend you uninstall it before installing Visual Studio 2019.
After installing Visual Studio 2019, using "Programs and Features" in the Windows Control Panel, remove your 10.x version AVR for .NET. Then do a full install of AVR for .NET 16.x.
Watch for .NET Framework version changes. Visual Studio will offer to upgrade a project to a newer version of the .NET Framework. AVR for .NET 16.x requires .NET Framework 4.7 or higher.
For Windows servers (for web applications)
Uninstall the current version of WebPak and then install ASNA DataGate WebPak 16.x.
To be able to maintain ASNA DataGate database names on the server or end-user PCs, download and install the ASNA DataGate Monitor 16.x from our downloads page. This article's video provides detail on database names.
For end-user Windows PCs
- Uninstall your current version of Windows Deployment and then install ASNA Windows Deployment 16.x.
- After installation, you will need new product licenses. Please send your license requests to email@example.com.
Test, Test, Test
As mentioned previously, we strongly recommend performing your upgrade on a test server or PC and testing your apps thoroughly there before installing the upgrade on a production box.
After the upgrade is installed on your production machine(s), test your applications in the production environment to ensure that all is well.