Thursday, June 22, 2017

Upgrades, Updates and Hotfixes in AX7

In Dynamics 365 for Operations (affectionately known as AX7), there is a clear distinction between binary hotfixes and metadata hotfixes (in LCS shown as "binary updates" and "X++ updates"). The product also has monthly platform releases and as of this writing a twice a year application release. I wanted to take a bit of time to explain the details of each and the distinction between them.

To provide context for this post, it's important to note that the product is split in two parts:
- Platform: kernel things, and some X++ code that are lower-level; things like batch framework, number sequences, print management, user info, etc.
- Application: The actual business logic. Customers, sales orders, production module, etc. Also some binary things like financial reporting (MR) and the SSRS framework for AX.

Platform Releases
After the release of Platform Update 4 (in February 2017), the platform now releases a monthly update. The platform consists of both the lower-level kernel binaries, as well as some X++ packages. However, the platform packages are "sealed" from over-layering, so even though you do get updated X++ code on your development boxes, you don't actually compile or customize these. You can extend them, of course. Each platform release contains any hotfix on the last platform, plus any new features (so they are cumulative - no need to install each one individually, just take the latest). Since this is just platform, the impact on the functionality is extremely minimal. Additionally, any code changes made by developers at Microsoft is checked for breaking changes (which are not allowed). This means the database schema cannot be changed (for the most part) and all APIs (method signatures etc.) should remain the same. This ensures any extensions won't break - the expectation is they don't need to be recompiled (i.e. you update platform, but no need to recompile/redeploy your extension packages). There are also backward compatibility checks to make sure older version of the application can run on newer versions of the platform.
In reality this all means that you can compile any code you have on an old platform, and deploy it on an environment with a newer platform - because the runtime is backwards compatible. As a result, many ISVs will develop and build their code on a "common" platform (for example, the fall release 2016 was released on Platform Update 3, and customers can install it on a newer platform (say, platform 7).
This also means that there are no individual hotfixes to pick. First, unless a really nasty issues appears, bugfixes will just come in the next month's update. But if there are critical fixes, they will be cumulative - meaning each new hotfix is just a newer build of the same platform; get the latest and you have all hotfixes.

Application Releases
The application actually consists of a few different things. Binaries and metadata. Application binaries are considered things like MR, SSRS components for AX, etc. Metadata is considered all the X++ code related to the application (sales orders, customers, etc.).
An application release is considered a major or minor version change. For example, the original version of AX7 had application 7.0. The fall release (2016) was 7.1. Spring release in 2017 is 7.2. Note that this is different than the platform - the platform will be backwards compatible, so there's no major or minor release change. An application release then also means it's both the binaries and the metadata combined as one release.

Now, how do you consume these updates and upgrades?

Application Metadata Hotfixes
Since as of this writing (2017!) you can still over-layer the application code, it means metadata hotfixes come in the form of X++ hotfixes. You have to install the hotfix on a development box, which fixes the existing code - and then you have to build and create a deployable package to actually consume the hotfix somewhere. You can download hotfixes from issue search of the "X++ updates" tile on an environment's page (at the bottom). Since these are just hotfixes, they have no impact on the actual application release you are running. You just have your original release, plus some hotfixes. Since you add those to source control to get built by the build VM, you only install them once and other developers will just synchronize them onto their boxes from source control.

Application Binary Hotfixes
Since the application is split in metadata as well as binaries, as explained above, you also need binary hotfixes next to the metadata hotfixes. These will be things like hotfixes for MR for example. These can be download from issue search, or also with the next update described. This will change once the application is sealed from over-layering.

Platform Updates
Platform updates effectively update your platform as described in the platform release above. A platform update can be download from the global asset library and deployed.

Binary Updates
On an environment page, there is also a tile called "Binary Updates". On environments of platform update 4 or newer, this effectively lets you download the latest version of the platform, as well as any application binary hotfixes. Since the tile is a combination of application binary hotfixes as well as platform updates, just installing a platform update from the global asset library (as described above) will not necessarily set the tile counter to 0 (zero) since there may still be applicable application binary hotfixes.

Application Upgrades
As of this writing, an application version is released twice per year (typically spring and fall releases). Since this changes the application functionality, it requires a code upgrade, full testing of the application and customizations, and a data upgrade.


WhatWhere to getContentsHow to DeployCode Upgrade RequiredData Upgrade required
X++ UpdatesEnvironment page
Issue Search
SCDPP package with X++ code changesInstall on Dev box, build/package, deployNO, but potential code conflict/merging required for over-layering codeNO
Binary UpdatesEnvironment pagePlatform Update (code+binaries)
Application Binary Hotfixes
LCS, manual runbookNONO
Platform UpdatesBinary Updates
Global Asset Library
Platform Update (code+binaries)LCS, manual runbookNONO
Application ReleaseLCS DeploymentEverything - application, platformRedeploy Environments (transparent for production environments)YESYES

Hope you like the retro HTML table styling.


  1. Thanks Joris! That is precious information!

  2. Thanks Joris, good overview of the different types of updates and how to obtain them. What I'd like to see though, is a better way of being up to date on the application X++ updates. I often just want to spin up an environment, apply all latest binary updates, and all X++ hotfixes.
    Sure I can select all hotfixes at once (currently 600+ of them for 1611), and try to apply them in VS. That'll break the 'Apply Updates' tool though. It just doesn't seem to be able to handle that many hotfixes at once.
    Anyway, what would be nice - besides a working Apply Updates tool - is the option to apply MS X++ hotfixes directly from LCS to a 'hotfix'-folder in the VSTS repo, with nothing but official hotfixes in it. It could even be set to check in each applicable hotfix automatically, whenever they became publicly available.

    1. On this blog I can't speak in my role as MSFT employee since these are all my personal opinions on this blog.
      That said, once the application is sealed the X++ hotfixing 'mess' will go away since they will become cumulative, and "cherry picking" hotfixes will no longer be possible.

  3. Great post, Joris!

    Could you also elaborate a bit around any dependencies between "Binary Updates" and "X++ Updates". Are there any dependencies there, or can you simply chose to install all "X++ Updates" and ignore "Binary Updates" (not recommended, but is anything preventing it).

    1. In theory, there are no dependencies. In reality there are probably a few. The reason is there have been new features in newer platforms, but nobody can use them until the application uptakes them. I think there have been hotfixes that have come out to enable these features in the app. Now, I suspect the dependency would be enforced (in that, the X++ hotfix won't show up if you don't have that update) but to be honest I haven't tried this or asked around how this works.
      So, that's why I _think_ but I can't say for sure.

  4. Thx Joris, helpful as always!

  5. Do you know of any blogs/documentation that explain the correct way to uninstall an application hot fix from a DEV box if you decide you don't want it? The 'Prepare' option handles all the changed AOT files (since it allows you to check in the previous versions before you apply the new versions). But when you undo the Pending Changes for the hot fix, while it rolls back the changed objects, it doesn't seem to remove any brand new elements that were added by the hot fix. Any guidance on that topic would be much appreciated. Thanks!

  6. Pls provide an updated doc for current platform

  7. Does it apply to on-prem deployments (service fabric) or only for dev one-box case because I am unable to apply any own custom packages or hotfixes or platforma updates on my on-prem sandbox environment. It just all fails at the end. I have fresh installed platform update 12 with app version 7.3. No forums left where to share knowledge regards issues with on-prem deployments :(