Creating a .NET Assembly, the importance of versioning

Everyone who has ever created a .NET DLL for his NAV project will probably have run into different kind of issues concerning versioning.

  • Either unable to overwrite without stopping the Server Instance
  • Not having the right assembly loaded
  • Having to replace your assembly in code and losing your events

In this post, I’ll have some information about versioning, the importance of versioning and some tricks.

Difference between the versions

Well, let’s start with the 2 types of versions we have in .NET:
– Assembly Version
– File Version

Both do something completely different, I’ll show you what a bit further.

But basically, the file version is merely the version show in File Details, while the assembly version is the version which is used by NAV as reference.

The basics

Let’s have a look at this sample:

I have created a simple Class Library with 1 function:
01_MyCode
After building, this is the result:
02_MyBuild

I copy my DLL into my server Add-Ins folder and create a simple codeunit:

03_MyGlobal 04_MyCode

And this is the result:

05_Result

Alright, let’s start playing with the versions. First I have added an extra function:
06_Changed Code

Then I copied my DLL to my Add-in Folder and guess what:

07_Object In Use

This means my DLL was referenced since the start of my NST and is in use. The only option is to stop my Instance and delete it before overwrite. By the way, this could result in all sorts of funky stuff, as Vjeko has already blogged about: Read here.

Here is where versioning will come handy.

Changing Assembly Version

09_AssemblyInfo

And this is what the file details show:
10_DLLDetails

Next I change my assembly version and build:
11_ChangeAssemblyVersion

So, what do we see in the File Details? Exactly, still showing 1.0.0.0.
I overwrite my file in the addin folder and this is what NAV shows when trying to view the available Assemblies:
13_ChangeAssemblyNavDetail

Only the lastest version is available, being the 1.1.0.0 assembly version (I had overwritten my previous file).

If I don’t change my code to the new assembly, and run it, I’ll get an error that assembly version 1.0.0.0 is not found.

Changing the File Version

This time, I’ll change only the file version:
14_ChangeFileVersion
Leaving the assembly on 1.1 and changing the file version to 1.2.
This is what the File Details say:
12_ChangedAssemblyVersionDetail
Still as expected right?

This time, I change my DLL name to add 1.2 in the name, and copy it in my Addin folder.

NAV still only shows 1 line, with assembly version 1.1. Which it will actually execute, you can only guess…
My code doesn’t need to be changed though. It will still run because the assembly version is the same

If I had overwritten the file, the new file should be used, without needing to change my codeunit reference, but… I might need to restart the Service Tier. Or all Service Tiers, if there on the same executable…

Wanted? Definitely not.

Changing both Assembly & File Version

17_BothChangedVersions

18_BothChangedDetail

20_MyAddInFolder

Also copied into the addin folder again, this is what NAV shows:

19_BothChangedNAVDetail

2 versions. Which can be used at the same time.

Versioning Conclusion

Keep your file / assembly version the same. It is much easier to know which version the file represents.

DO version… Keep your version in a folder per version.
This way, we can put a newer version into the production environment without having to stop it when in use.
This way, we can test the new assembly if the Service Tiers are on the same executable, but with different instances.

What are the issues?

Well, let’s check this: I have created version 1.4 with an event in it:
30_WithEventCode

In NAV I did the following:
31_NAVWithEvents

This creates my event, and I have changed my code as following:
32_WithEventNAVCode

Let’s assume I have made little mistake in my .NET code and only change the sleep to 5000 milliseconds:
40_SleepLonger

When in NAV I select version 1.5.0.0. This happens:
41_SleepLonger_NAV

If I choose yes, this happens:  42_SleepLongerResult

The event is created again, but my code is gone…
When I select no, the assembly isn’t changed.
It is a bit annoying…

It is possible to export as text, and change the assembly version, so the code will take the correct version without losing your code, but your signatures will not update if they were changed.
To make this easier, you should keep you DLL references in a single codeunit, and use this codeunit everywhere you wish to use the assembly. This makes it easier for you to update all your assembly references.

A solution for the changing signature is to create a custom EventArguments class. Just a simple class with properties. Always return this in the signature. This way, you could add properties in the class, and use them in NAV without changing the signature.

3 thoughts on “Creating a .NET Assembly, the importance of versioning

  1. changing the assembly version may allow using the dll out of the box without restarting the NST, but also forces you to recompile the objects using the newer assembly. Fixing Bugs in the .net-code forces you to update all references, also in other projects (or add a assembly-part in app.config).
    This is really bad!
    I update the assembly-Version only if the api is not backward compatible anymore and restart the NST to release the old version of the dll. Furthermore i seperate the install-dirs (\80\Service) per database. This allows each install (and all of its instances, that run on the same objects) to use “their own” dlls.

  2. Hello What is the advantage of using DotNet instead of Automation ? If I use DotNet data type for my development. Do I need to include .dll file in every client PC ? or If its okay If I keep it inside only the Server ?

    • DotNet and automation is something completely different.
      Automation are the older DLL/OCX types, which you typically installed with regsvr32. These are in the latest version not really supported.
      DotNet is real .NET dll or .net libraries.

      When using DotNet with .net libraries, you don’t need to copy around anything, these should be installed at all locations, since they are in the .net framework.
      When using DotNet with custom dll, in most cases, you should be good with putting the DLL in the addin folder of the service tier.

Leave a Reply