Updating Azure Client Libraries

Jump to: navigation, search

From time to time, it may be desirable to update to the latest version of the Azure client libraries. Old libraries are typically supported for many years, but eventually the current libraries must be incorporated. In addition, new libraries may contain important bugfixes.

New libraries are available with NuGet. Standard NuGet update mechanisms are supported using alfa2_acr.hak\ALFA.Shared\packages.config. This guide assumes the use of Visual Studio to update NuGet packages.

NuGet Packages Used

Currently, the following packages are referenced from NuGet:

  • Microsoft.Data.Edm.5.6.4
  • Microsoft.Data.OData.5.6.4
  • Microsoft.Data.Services.Client.5.6.4
  • Microsoft.WindowsAzure.ConfigurationManager.3.1.0
  • Newtonsoft.Json.6.0.8
  • System.Spatial.5.6.4
  • WindowsAzure.Storage.4.3.0

We directly use WindowsAzure.Storage, the other packages are dependencies of the Azure Storage client library and have to be included so that the Azure Storage client library works. ACR_AssemblyLoader is responsible for pre-loading all dependencies, so if a brand new dependency were to be added, it would have to both be added as a reference to ALFA.Shared and added to the resources in ACR_AssemblyLoader, with AssemblyLoader.cs changed to preload the new assembly.

Package Update Procedure

To update to a new Azure client library set:

  1. Open ACR_ManagedScripts.sln in Visual Studio
  2. Go to the Tools menu, NuGet Package Manager, Manage NuGet Packages for Solution...
  3. Click on Updates on the left-hand tree.
  4. Click on All under Updates. Updates will be checked to see if any are available.
  5. Click Update All to retrieve new packages. This removes the old packages from CLRScript\packages and installs new packages to that location.
  6. Open ACR_AssemblyLoader\Properties\Resources.resx and update the relative paths for each package under CLRScript\packages, to point to the new paths. Usually this is just a matter of changing the version number to match. You want the net40 packages for .NET 4.0 which we use (technically we could upgrade to 4.5 or 4.6 as these are compatible and all servers are on Windows 7 or higher but we have not done so yet).
  7. Update the dependency references in ALFA.Shared to point to the new file locations. It's usually easiest to remove the references to each of the packages above, then re-add them (right-click References, Add Reference..., Browse, Browse... button, navigate to each of the directories in packages and add the appropriate package (typically net40) .dll.
  8. Clean up extraneous app.config files by removing them from projects. Sometimes, the NuGet update might create extraneous app.config files. These are used to map old versions of referenced dependency assemblies to new versions (for example, Microsoft.Data.Edm.5.6.0 to Microsoft.Data.Edm.5.6.3). These aren't needed except for CLR script projects. ALFA.Shared.dll and VaultTransferTool should keep these, however.
  9. Test to make sure that everything works, vault and updater operations.
  10. Remove old directories from packages from git (in CLRScript\packages, git rm -r <packagedir>, for each superseded package).
  11. Add new directories from packages to git (in CLRScript\packages, git add <packagedir>, for each superseded package).
  12. Add & commit changes to git. Make sure to check that there aren't unexpected, untracked changes.