Docs: Nav Upgrade

Mon, 01 Jan 0001 00:00:00 +0000

Anti-Patterns in NAV Upgrade

By Carlos Raul Garcia and Bogdana Botez at Microsoft Development Center Copenhagen

Context: when NAV is upgraded, whether on-premises or in the cloud, developers have the chance to write upgrade code to move data across changing data structures. Writing good quality code will help successful upgrades.

General on upgrade

Problem: assuming that the upgrade table contains data.

If the table is empty, it means that either the upgrade has run, or there was no data in the original tenant; in both cases, the upgrade code should exit immediately.

Solution: if using an upgrade table, always validate that the table contains data before doing anything.

Upgrade code, can it be rerun safely?

Problem: if the upgrade code is not written in a way that makes it runnable twice (idempotent), then several failures can happen, including something as critical as data corruption.

In on premise NAV installations, if something fails at upgrade, there is no way to run only the “remaining” tasks. You will need to run the whole upgrade again, and might end-up with data that you cannot trust.

What about the cloud? In Platform As A Service (PaaS), in some situations, the upgrade code needs to be run twice (for example, when moving tenants from a broken/frozen VM to a healthy one).

Solution: Make sure each of your upgrade procedures only kicks in if it didn’t run before.

Examples

The examples below have happened in real live NAV PaaS upgrade:

Table data overwrite

Problem: at upgrade, a new column has been added to a table and initialized with default values. In the meanwhile, during production, some of the default values are changed to production real life values. The second time the upgrade runs, those values will be overwritten with defaults, any personalization lost.
Solution: before initializing with default values, check if non-default values exist.

Crash on math operations

Problem: one tenant upgrade managed to divide by zero, by assuming a non-zero value.
Solution: don’t assume values can never be zero, always check before using them in divisions.

Use of external components

Problem: a one-time registration through web services to an external service failed when attempting to register a second time.
Solution: check if already registered, before attempting again.

Parallelism

Problem: Upgrade procedures can be run in parallel, causing issues when different procedures attempt to modify the same table at the same time.

When modifications to the same table are being made from two or more different procedures, there is no guarantee on sequential run, or on a certain order they will be run in.

Solution: if sequential or ordered execution is needed, make the affected upgrade procedures local and call them all, in the desired sequence, from a public upgrade procedure.

Access to cloud machines

Problem: dependencies on manual installation steps do not fit in the cloud.

If Dynamics NAV is installed on-premises, then any additional setup (like dependencies of external dlls, manual configuration steps etc.) can be done manually or semi-manually by the IT admin, at first setup and upgrade.

In the cloud, NAV partners don’t have access to the machines – hence they cannot deploy and configure those external dependencies as they did in the old on-premises installations.

Solution: Don’t assume you will have access to PaaS or SaaS machines. Build your solution in such a way that it doesn’t depend on executing manual configurations on the host machine.

Docs: Reusable Bugs

Mon, 01 Jan 0001 00:00:00 +0000

By Bogdana Botez, Andreas Moth, Eric Wauters (waldo), Elly Nkya, Nikola Kukrika

April 1st, 2015

Abstract

It is difficult to come up with new and different bugs in each release, and it is a waste of resources to not use the ones which already had proven successful in the past. To avoid reinventing the wheel, we propose to come up with new innovative ways to create bugs that are reusable and generic enough to be used in various places of the application.

Examples

Option Strings

One example of a reusable bug is to find a heavily used table, like table 36 Sales Header, and observe one of the more important fields of type Option, for example Document Type. The OptionString property has the following value: Quote,Order,Invoice,Credit Memo,Blanket Order,Return Order, which you should update to add one option, for example Transport Order in the beginning.

The main benefit of this reusable bug is that code changed in one place, has impact in multiple sides on the application: document creation and handling, posting etc.

Application Management

Codeunit 1, ApplicationManagement is a good place for creating reusable bugs. A simple INSERT on the RecRef on the first line of OnDatabaseInsert will create a sure and versatile bug that is reusable all over the application. Redundancy on database insertion ensures that data is surely conveyed to the data storage layer, twice.

God objects

We are considering to no longer make localization builds for countries. It consumes lab resources to keep running multiple country builds. Instead, we will merge everything into one single build. This is a bigger scale implementation of the “God object”. Inside this unique build, we will use IF statements and sporadically CASE statements to select each country’s behavior. For more help on how to use IFs, see also the IF .. THEN|ELSE C/AL Coding Guideline.

Field length economy

When you post a document, make sure to transfer data to a field that is smaller than the field you are assigning from. This will not immediately be caught and will only hurt a subset of the customers who uses Microsoft Dynamics NAV to its fullest.

Guidelines

When bug addition is not entirely obvious, there is a second way to approach the problem. By following some general coding best practices like the ones described below, reliable bug innovation is facilitated and can come naturally as a collateral effect.

Code structure

Put everything in one function and only use comments to explain the structure of your code. And don’t use functions - because this only complicates things… having to navigate from function to function, and completely lose track of where you are in the business logic.

On top of that .. put everything in one codeunit. Because also that will simplify and make your structure more readable.

Use Hungarian Notation on your variables, because at any time, you need to know what type, and what context your variable is on.

Declare all your functions and variables global, so they are available at any time.

Don’t do Unit Testing

Unit testing adds complexity and extra time to the stuff you’re doing. Also, it eats up extra codeunits which means: it costs money. You will never be able to foresee all scenarios possible, so you’re destined to forget and not test everything. So you will save time in not doing unit testing.

Never add images to actions

Because there is an image by default. When you don’t provide an image on an action on a page, the application will foresee a ball… and when you never do it, your application will have a very consistent way of showing your actions, by providing that picture of that ball. On top of that, you’ll save time.

Do not care about ControlIDs

When you’re doing development of your product, do not care about ControlIDs, and just leave the Offset ID to the default value of 0. This way, when merging, you will receive nice notifications, saying both you and Microsoft have added functions in that objects. You can use this feature to document all these places.

Hooks

Never apply the hook pattern. Hooks will only reduce upgrade time. This means, you will only shortly enjoy using the AMU (Application Merge Utilities). The more you change in default application, the longer it takes to upgrade, the longer you will enjoy the toolkit

This can be taken one level higher. Simply you are not hardcore if you do not use notepad to resolve all of the merge issues.

How to use RecRef

Why fuss around declaring specific table variables, just generalize, all you need is one, two, or perhaps three RecRef variables, with a few IFs and CASEs here and there for reflection, to carry you all the way.

Arguments

Using only a few arguments on the functions is a sign of a weak developer. Stick in as many arguments as possible on the function, even if you are not using them, they could be useful in the future.

Just another field / action

Thinking of the design is overrated, each problem can be solved by adding an additional field or the table/page or with adding another action. We all know this has worked well in the past.

Reusability

We have decided that each time we fix a bug, we now also explain how it can be applied as a pattern. We then use anti-virus software to search for these patterns, to make sure we do not re-introduce these bugs anywhere else in NAV.

Business logic placement

As a best practice, we have also decided to move code into pages. Business logic should no longer be in tables and codeunits, but instead pages should know and be aware of the context and update it accordingly. As opposite to tables and codeunits, pages are aware of the context.

Conclusion

Happy April Fools’ Day.

Disclaimer: this is inspired from IETF documentation published on April 1st, like for example the revolutionizing IP over Avian Carriers standard.

alguidelines.dev - Business Central Design Patterns – 2. Anti-Patterns