Increasing the length of non-PK fields

Though this blog posts will feature some AppSourceCop rules, you should be aware of this topic if you develop any kind of app that other apps have (or might have) a dependency on.

Once upon a time … At the very beginning, developers of AppSource apps for Business Central were not allowed to change any field properties: AppSourceCop error AS0004 prevented the change of data type and field length, as it was regarded as a breaking change for dependent apps. Already September 2020, this error has been reduced to the data type change check. Since then, there are error AS0080 to prevent a field length decrease, and error AS0086 to prevent a field length increase – both for non-primary key fields. Lastly, according to a docs commit, already in December 2021 (!) error AS0086 turned into warning AS0086. Did I just say “lastly”? No, there is also error AS0118 to prevent any field length changes for primary key fields. The docs for AS0118 were created in June 2023, but I suppose just the docs were late, not the rule itself …

To summarize it: you may directly increase the length for non-primary-key fields, but you shouldn’t – or at least not without any precautions.

We will talk about three different coding approaches to increase a field length:

1. Old way: switching fields
2. Warn now and increase later
3. Increase right away
4. Conclusion

Old way: switching fields

The old way for increasing field lengths was just the same when decreasing field lengths: replace the field with a new field. Next to putting your old field to ObsoleteState = Pending which will send out warnings to other apps depending on yours, this method requires writing upgrade code to copy the values from the old to the new field, and to publish at least two app versions. Using conditional directives might help you in this process, as I have explained in another blog post: Conditional Directives – CLEAN22 demystified.

These instructions are outdated since the error AS0086 became warning AS0086. There is no need to create a new field and such to move data, as you will learn in the following section.

Mind that the switching field method still applies for decreasing field lengths, which is prevented by error AS0080.

Warn now and increase later

What should you do? The docs describe it now as follows:

If increasing the length of the field is required, the recommended approach is to mark the field as Obsolete Pending, and in a later app version, remove that state again, and just increase the field length and remove the ObsoletePending state.

AppSourceCop Warning AS0086 – How to fix this diagnostic?

Let’s learn from the Base Application, which published main version currently is 23. In several tables of BC 24, the Home Page field will be increased from Text[80] to Text[255]. These are the steps:

1. Next main version: warn dependent apps.
   In BC 24, the field will be set to ObsoleteState = Pending – but only temporarily.
   
2. In BC 24 + x (whereas x usually equals 3), increase the field length.
   Remove ObsoleteState.
   x = 3 means that dependent developers can prepare throughout BC 24, 25 and 26.

As mentioned earlier, this process can be facilitated by using conditional compiler directives. This is a Home Page field still in BC 23:

        field(103; "Home Page"; Text[80])
        {
            Caption = 'Home Page';
            ExtendedDatatype = URL;
        }

This is how the code will look like in BC 24:

#if not CLEAN24
        field(103; "Home Page"; Text[80])
        {
            Caption = 'Home Page';
            ExtendedDatatype = URL;
            ObsoleteReason = 'Field length will be increased to 255.';
            ObsoleteState = Pending;
            ObsoleteTag = '24.0';
        }
#else
#pragma warning disable AS0086
        field(103; "Home Page"; Text[255])
        {
            Caption = 'Home Page';
            ExtendedDatatype = URL;
        }
#pragma warning restore AS0086
#endif

As we can see, the compiler directive CLEAN24 helps to mark code that will be removed later, and to add future code already now so it won’t be forgotten.

And this will be the same field coded in BC 27:

#pragma warning disable AS0086
        field(103; "Home Page"; Text[255])
        {
            Caption = 'Home Page';
            ExtendedDatatype = URL;
        }
#pragma warning restore AS0086

Hold on, why is Microsoft disabling AS0086? It looks like that in order to prevent breaking changes, they are applying the AppSourceCop themselves. That’s good, because it means that you (as an AppSource app developer having the AppSourceCop activated) can copy this pattern.

Between 27.0 and 27.1, there won’t be another field length increase, hence no warning AS0086 will be thrown. As a result, the pragma can be removed. I would expect the BC 27.1 code to look like this:

        field(103; "Home Page"; Text[255])
        {
            Caption = 'Home Page';
            ExtendedDatatype = URL;
        }

Will it actually happen? I doubt it, but that’s just my guess.

When you apply this pattern for your own app, mind that the moment you set the ObsoleteState = Pending, you will generate new AL0432 warnings in your own code for every reference to your field. To get rid of these warnings, just pragma them out, but don’t forget to remove the pragmas once your field has been increased.

To help me find everything to remove, I use compiler directives (and a DevOps task pointing me to CLEAN_BC24):

#if not CLEAN_BC24
#pragma warning disable AL0432
#endif
        // My code calling the Home Page field
#if not CLEAN_BC24
#pragma warning restore AL0432
#endif

However, you won’t find that in the BC standard code.

If you don’t like using the ObsoleteState for not removing a field but just generate a warning temporarily, then give your vote to this BC Idea: Add new Property for Table or Field Changes that will receive breaking changes.

Increase right away

Warnings and dependent apps may, but should not, be ignored. As a result, you could increase the field length directly, without any precautions:

        field(103; "Home Page"; Text[255])
        {
            Caption = 'Home Page';
            ExtendedDatatype = URL;
        }

Pros:

• No planning required, no code parked in inactive state
• No waiting time: the new field length is immediately available.

Cons:

• Raises warning AS0086 for yourself, for the duration of one app version.
  Either ignore it, or use a pragma as Microsoft did above.
• No warnings for code referencing your field, even not for your own app. Dependent apps might break.
  To mitigate, you could temporarily set your field to ObsoleteState = Pending and add a helpful ObsoleteReason.

Conclusion

I hope I made clear why simply increasing fields is not a good idea – as long as other apps depend on yours. Try to always send out warnings to dependent apps. The sooner, the better.