21WOJP – Week 2 - Migrating Your .NET Code

This week we'll talk about migrating your .NET applications to AutoCAD Civil 3D 2013. Assuming your Civil 3D specific code is well centralized, it should be very simple to migrate. It took me around thirty minutes to port the code for Colibra and this blog and that includes dealing with some VB.NET idiosyncrasies I wasn't aware.

Let's start by talking about AutoCAD. As you know, Civil 3D is based on AutoCAD, which means that you have access to the AutoCAD API as well as the Civil 3D API. I will not sped too much time writing about the changes in the AutoCAD API, but I will highlight a couple of things that you most likely will run into. You should read the article "Migrating .NET applications to work with AutoCAD 2013" by Kean Walmsley before you begin. Everything in his article applies to Civil 3D; especially, if you do heavy use of the AutoCAD API.

Important AutoCAD API Changes

Due to the work the AutoCAD team has done with the "Big Split", you will have to add a reference to a new "AcCoreMgd.dll" module. Through the "Big Split" some functionality that used to be in "AcMgd.dll" has been moved into this new module, and you will have to reference it in your projects. This change breaks binary compatibility of the AutoCAD API from previous releases, so you have to take that into account when planning porting your projects.

"AcMgd.dll" still exists providing application specific functionality. Some pieces; however, extend classes that are no longer located in “AcMgd.dll” and have been moved to "AcCoreMgd.dll". The AutoCAD team has decided to use extension methods to expose the extended functionality, which means some things that previously were accessed through an object property are now accessed through an extension method. An example of this change is the "StatusBar" property on the Document object, which now can be accessed through the "GetStatusBar()" extension method in the "DocumentExtension" class. What this really means to you is that if you have code using a property (i.e. 'StatusBar') from an object that does not compile in 2013, you should check if there is a similar 'Get' method implemented in an 'Extension' class (i.e. 'GetStatusBar()').

.NET Framework 4.0

Our previous release allowed extensions to be built using earlier versions of the .NET Framework. Depending on the functionality you were using, you could build your projects targeting .NET 3.5 or earlier version, and .NET 4.0 was also supported. In 2013, you must build your projects targeting .NET 4.0. The work you will have to do will depend on your project and the functionality you are using from the framework, but I have not see any problems with the projects I have worked. Besides, you might have already ported your code to the latest framework, in which case, this will not affect you.

Namespace Structure

One of the things that has always bother me about the Civil 3D API since I started to work with it was the complexity of the namespaces. To do any trivial task with the Civil 3D API, users were force to include different, related namespaces; even though, the classes they were using were related to each other and there would be no name collisions among them.

This release we tried to simplify the namespace structure by removing namespaces related to features. This change also causes a binary incompatibility with previous releases, but I believe it will be for the best moving forward. The change is very simple. In the past you will have a namespace that includes a Civil 3D feature name in it; for example "Autodesk.Civil.Land.DatabaseServices". In 2013, you should remove the "Land" part of the namespace in your using declarations, resulting in a simpler "Autodesk.Civil.DatabaseServices namespace. We have always be very careful not to introduce class names that can cause a collision; therefore, your code should compile just fine by removing any use of "Autodesk.Civil.<feature_name>.<service_name>" and including "Autodesk.Civil.<service_name>.

Conclusion

Migrating your Civil 3D applications to the 2013 release should be a straight forward operation provided that your Civil 3D specific code is well centralized. The Civil 3D specific changes are related to the namespace restructuring work that was done in 2013, which will simplify the code organization for future releases.

You will have to update your references to the 2013 versions and reference the new “AcCoreMgd.dll” assembly in your projects. The 2013 release is not binary compatible with previous releases, and you will have to recompile your applications.

You will also need to consider the changes made to the AutoCAD API because some of them will affect you when working on Civil 3D. Pay particular attention to properties converted to extension methods. The compiler will help you to spot the places where a change is required, and the changes are a simple as finding an extension method in the format ‘GetPropertyName’ where before was ‘PropertyName’.

P.S. Civilized Development Source Code

As you know, you can find all the source code from this blog at this BitBucket repository. You can clone the repository or download it as a ZIP file. I also posted a ZIP with all the code, which you can download from here. If you are interested in the 2012 version of the source, I created a fork of the repository, which you can clone or download from BitBucket. I will not update this fork with new functionality, since most of my upcoming posts will be based on the new functionality in 2013, but it may serve you as starting point to go through the migration process by yourself.

Comments

[Drew]

The new namespace structure is a huge improvement, and really cleans up the code, and makes it easier to find what you're looking for. Good job!