Civilized Development

Civil 3D Wish List Survey for 2013 Available

Once again, ADN is hosting a survey to identify the Civil 3D API features important to you. We take very seriously your feedback, and if you review past survey results with the API functionality we have implemented, you’ll notice they match very well.

Don’t let go this opportunity to be heard. Take the survey and let us know which areas we need to work on to improve the API. You can take the survey here.

Download Civilized Development Source for 2014

This is a quick post to inform you that the Civilized Development source has been ported to the Civil 3D 2014 release. No additional samples have been added; we will do that in upcoming posts, but you should be able to build and run the samples against the new version of Civil 3D. You can download the source from the Civilized Development Repository.

Augusto Releases Snoop DB for 2014

Good news if you have updated to Civil 3D 2014. Augusto Goncalves has updated his magnificent tool SnoopDB to work with the 2014 release. The tool adds some new functionality allowing to access all the properties exposed by the new Corridor API, as well as support for Point Groups. The main new feature is the ability to navigate from one entity to another by clicking a related property.

This tool is very handy to analyze the structure of your Civil drawings, and it comes very handy to troubleshoot issues and find information that it is not immediately visible in the drawing. Download the tool and source code, and check Augusto’s article for more information.

AutoCAD Civil 3D 2014 Released

You go on vacation for a couple of weeks and all of the sudden Civil 3D 2014 is out the door and everyone has beat you to talk about it. It has been a very long time since my last post. As you can imagine, my team and I were very busy working on our new release, and that left me very little time to write new posts. Now, the release is out the door and it is full of new features and functionality that I will be writing about in the upcoming weeks.

Unfortunately, this year I cannot commit to a long series of posts covering each and every piece that it is new in this release. Last year, it took quite a while to go over all the functionality and work always gets in the way. I’m, therefore, concentrating in the pieces that are more important to you, so do not hesitate to contact me requesting topics for discussion.

If you want to have a sneak-peak of what’s new in the AutoCAD Civil 3D 2014 API, you can check the Infrastructure Modeling DevBlog, which already covers the new features. Between them covering very important aspects of the API and myself giving a more in-depth overview of the feature, we are set to provide you with all the information you need to use the new APIs. So stay tuned because there is a lot of information coming your way.

API Survey and AEC Dev Camp 2012

Let’s take a quick break from the 21 Weeks of Jay Peak series to talk about a few things going on with the API. First, let me remind you that ADN has posted a wish list survey for the AutoCAD Civil 3D API. The deadline to fill the survey is June 11th, and you fill it up to give us your feedback and help us plan future releases. For some reason, I thought I posted about the survey when it was first published, but I cannot find the post, so maybe I did not. I apologize either way, and I hope you can take some time to fill it now.

This week ADN is running the AEC Dev Camp in Waltham MA. I was there yesterday giving a lecture and participating in a couple of sessions. It was nice to meet some of you or see you again face to face. I think the sessions went well and there was plenty of good discussions. We will take all the feedback with us and consider it very carefully for future plans.

My session yesterday talked about the COGO Points API. If you have been following me for the past few weeks, you have read a lot about it already, and you will read more in upcoming weeks. But in case you are interested, you can download all the source for the lecture from the CogoPointsDemo repository I created at BitBucket. Materials for all sessions have been posted to a public Buzzsaw project. There is plenty of good materials for all AEC applications development, so I am sure you want to check it out.

If assisted Dev Camp this year, it was nice to see you; if you did not, keep an eye for upcoming events. They are always fun.

21WOJP – Week 4: Document Management

Last year, I wrote a post on how to implement a DocumentManager for Civil 3D documents. The motivation was to overcome the limitations in the Civil 3D API that made very difficult to work with multiple documents at once. Many of you have pointed out how difficult is to keep track of the different document and database objects even when the code is well abstracted into an owned 'Document' and 'DocumentManager' classes.

In Jay Peak, we have introduced a new static method 'GetCivilDocument() in the 'CivilDocument' class, which allows you to instantiate a 'CivilDocument' object from an AutoCAD 'Database' object. This new method highly simplifies the process because it allows you to implement all document management through the AutoCAD API; therefore, your 'DocumentManager' abstraction should only depend on the AutoCAD API and its document management functionality. From an AutoCAD 'Document' object, you can access the 'Database' object, which in turn allows you to instantiate a 'CivilDocument', and from these objects you can also access their COM instances.

In this post, I will go through the process of porting the 'Document' and 'DocumentManager' classes in 'Colibra' to make use of the new functionality and remove as many dependencies as possible.

Porting ‘Colibra.Document'

Looking at last year's implementation, the first thing we notices is that the 'Colibra.Document' class provides an internal constructor that takes both an AutoCAD 'Document' object and an instance of 'CivilDocument'.

C#

internal Document(acadappsvcs.Document acadDoc, 
  CivilDocument civilDoc)
{
  m_ThisAcadDocument = acadDoc;
  m_ThisCivilDocument = civilDoc;
  m_ActiveTransaction = null;
}

VB.NET

Friend Sub New(acadDoc As acadappsvcs.Document, _
  civilDoc As CivilDocument)
  
  m_ThisAcadDocument = acadDoc
  m_ThisCivilDocument = civilDoc
  m_ActiveTransaction = Nothing
End Sub

This is no longer necessary because we can access the ‘Database’ object from the AutoCAD ‘Document’, which will allow us to instantiate a ‘CivilDocument’. Therefore, our first change will be to remove the ‘CivilDocument’ parameter from the internal constructor and initialize the member variable using the ‘Database’ object.

C#

internal Document(acadappsvcs.Document acadDoc)
{
  m_ThisAcadDocument = acadDoc;
  m_ThisCivilDocument = CivilDocument.GetCivilDocument(
    m_ThisAcadDocument.Database);
  m_ActiveTransaction = null;
}

VB.NET

Friend Sub New(acadDoc As acadappsvcs.Document)
  m_ThisAcadDocument = acadDoc
  m_ThisCivilDocument = CivilDocument.GetCivilDocument(
    m_ThisAcadDocument.Database)
  m_ActiveTransaction = Nothing
End Sub

At this point, our project will not compile because we have to update every location where we are instantiating a ‘Colibra.Document’ object to remove the ‘CivilDocument’ parameter. Thankfully, our code is well abstracted; therefore, the only class we need to update is the ‘Colibra.DocumentManager’ class.

Porting ‘Colibra.DocumentManager’

‘Colibra.DocumentManager’ had the responsibility to keep in sync the AutoCAD ‘Document’ object with its corresponding ‘CivilDocument’ object. This is no longer necessary, so we can start updating and refactoring the implementation.

There are two public interfaces that instantiate a ‘Colibra.Document’ in ‘Colibra.DocumentManager’: the static property ‘ActiveDocument’ and the static method ‘OpenDocument’. The implementation of both of these public interfaces make use of a private method ‘createNewAndActivateFromAutoCADDocument()’, which was the place we insured both objects were kept in sync.

C#

public static Document ActiveDocument
{
  get
  {
    if (m_ActiveDocument == null)
    {
      createNewAndActivateFromAutoCADDocument(
        acadappsvcs.Application
        .DocumentManager.MdiActiveDocument);
    }
    return m_ActiveDocument;
  }
}

public static Document OpenDocument(string fileName)
{
  acadappsvcs.Document acadDoc = acadappsvcs.Application
    .DocumentManager.Open(fileName);
  createNewAndActivateFromAutoCADDocument(acadDoc);
  return m_ActiveDocument;
}

private static void createNewAndActivateFromAutoCADDocument(
   acadappsvcs.Document acadDoc)
{
  CivilDocument civilDoc = getCivilDocumentAndActivate(acadDoc);
  m_ActiveDocument = new Document(acadDoc, civilDoc);
}

private static CivilDocument getCivilDocumentAndActivate(
  acadappsvcs.Document acadDoc)
{
  acadappsvcs.Application.DocumentManager.MdiActiveDocument 
    = acadDoc;
  return CivilApplication.ActiveDocument;
}

VB.NET

Public Shared ReadOnly Property ActiveDocument() As Document
  Get
    If m_ActiveDocument Is Nothing Then
      createNewAndActivateFromAutoCADDocument(
        acadappsvcs.Application. _
        DocumentManager.MdiActiveDocument)
    End If
    Return m_ActiveDocument
  End Get
End Property

Public Shared Function OpenDocument(fileName As String) As Document
  Dim manager As DocumentCollection =
    acadappsvcs.Application.DocumentManager
  Dim acadDoc As acadappsvcs.Document = manager.Open(fileName)
  createNewAndActivateFromAutoCADDocument(acadDoc)
  Return m_ActiveDocument
End Function

Private Shared Sub createNewAndActivateFromAutoCADDocument(
    acadDoc As acadappsvcs.Document)
  Dim civilDoc As CivilDocument = getCivilDocumentAndActivate(acadDoc)
  m_ActiveDocument = New Document(acadDoc, civilDoc)
End Sub

Private Shared Function getCivilDocumentAndActivate(
    acadDoc As acadappsvcs.Document) As CivilDocument
  acadappsvcs.Application.DocumentManager.MdiActiveDocument = acadDoc
  Return CivilApplication.ActiveDocument
End Function

With the new API, we do not need to activate a document before accessing the ‘CivilDocument’ instance, so we can remove the implementations of ‘createNewAndActivateFromAutoCADDocument()’ and ‘getCivilDocumentAndActivate()’. To remove these methods, we need to update the implementation of the ‘ActiveDocument’ property and the ‘OpenDocument()’ method, then we can remove them.

 

C#

public static Document ActiveDocument
{
  get
  {
    if (m_ActiveDocument == null)
    {
      m_ActiveDocument = new Document(acadappsvcs.Application
        .DocumentManager.MdiActiveDocument);          
    }
    return m_ActiveDocument;
  }
}

public static Document OpenDocument(string fileName)
{
  acadappsvcs.Document acadDoc = acadappsvcs.Application
    .DocumentManager.Open(fileName);
  return new Document(acadDoc);
}

 

VB.NET

Public Shared ReadOnly Property ActiveDocument() As Document
  Get
    If m_ActiveDocument Is Nothing Then
      m_ActiveDocument = New Document(acadappsvcs.Application. _
        DocumentManager.MdiActiveDocument)
    End If
    Return m_ActiveDocument
  End Get
End Property

Public Shared Function OpenDocument(fileName As String) As Document
  Dim manager As DocumentCollection =
    acadappsvcs.Application.DocumentManager
  Dim acadDoc As acadappsvcs.Document = manager.Open(fileName)
  Return New Document(acadDoc)
End Function

Running all the unit tests, we can see that everything passes, so our port was successful. The final implementation of ‘Colibra.DocumentManager’ is much simpler, and the design fits better to extend its interface and provide additional functionality our application may need. The fact that last year we provided the ‘Colibra.Document’ and ‘Colibra.DocumentManager’ abstractions has helped us to make the changes because they were well centralized and our client code was not directly dependent on the AutoCAD and Civil 3D APIs.

 

You can download the full source for Colibra from this link, or download the source repository from BitBucket. BitBucket will also allow you to download the entire repository as a ZIP file.

21WOJP – Week 3 - Getting Help

Last year, we made the decision to go on-line with the API help and documentation. Despite the initial negative reaction from some of our customers, I still think it was the right decision, and we went the same route this year.

Missing documentation is bad, but inaccurate, incomplete documentation can be even worse. Having the documentation on-line allows us to update it at any point in time and improve it over time. Last year, we were able to add additional articles to the Developer's Guide after the product shipped. We would not have been able to do it if the documentation resided locally on your machine. And in the future, we are planning to have more releases/improvements for the documentation as new articles and samples are written.

But this series is about Jay Peak and what we have done in the new release of Civil 3D, and when it comes to documentation, we have done a lot. Some results will show immediately, others will appear very soon, and like I said, we will deliver more improvements in shorter cycles. Let's take a look at what's new and how you can get some help.

Where's the Help?

You can access the API documentation from the AutoCAD Civil 3D 2013 WikiHelp site. This site provides access to all the product documentation as well as the API. You can find articles, tutorials, videos, and links to other resources, and it is the first place to find information about Civil 3D in general. You should add that location to your bookmarks and keep it handy.

What's New with the Developer's Guide

This year, we were able to add several articles to the Developer's Guide that cover, not only the functionality in the 2013 release, but also the functionality made available in 2012 for which we didn't have any new content. Because of our ability to update the documentation at any point in time, we added the applicable articles to the 2012 Developer's Guide to keep things up-to-date.

The new version of the Developer's Guide includes articles for the Surfaces .NET API introduced last year, as well as articles for the COGO Points .NET API, which is new to the 2013 release. These articles go deep into the functionality of the API and are a great resource to understand the design and implementation of the features.

Introducing the New Reference Guide

One of the biggest efforts this year regarding the API documentation has been the brand new Reference Guide. We spent quite some time researching tools and processes that would allow us to provide a better reference for all the available APIs and make them more valuable to all of our customers. Some improvements you will notice right-away; others will appear over time. This is an ongoing effort, and we are committed to it.

The first change you will notice is the new look and feel of the Reference Guide. We did some research of documentation tools that generate HTML documentation ready to be posted on-line and that can be integrated with our build process. The result a more modern, up-to-date Reference Guide generated every time we build Civil 3D. This allow us to release updates at any time including the latest and greatest information. We can fix any problems we find, and we can make changes according to the feedback we receive (more on that below).

One of the most requested improvements to our documentation is to provide more and better examples. You speak, we listen. The new Reference Guide allows us to embed sample code for each of the classes and members we document. You will notice that some of the new features are already providing small snippets of code that demonstrate their use. Again, we can update this over time, and we will be providing more and more code samples.

We created a new documentation review process to insure the quality of the documentation is the highest. You will see that classes, methods, and properties are better documented, and it is likely they will get even better in the near future. Of course, good documentation is kind of subjective, so we will need your help and feedback with that, which leads me to the next improvement.

Feedback links in the Reference Guide have been broken for quite some time. Not any more. Not only do they work, but submitted feedback does not go into a bucket that no one is monitoring anymore. When you submit your feedback it goes directly to me (and other members of the API engineering team). That's right, you submit your feedback, I get an e-mail. I have total confidence in the community to provide us with comments and suggestions on how to improve things even more, and find problems with the documentation where things are not correctly stated or do not work as described. I am also sure all of you will be very respectful to the engineering team when submitting your feedback and that I will not need to ignore/delete your e-mails.

How about getting help right in Visual Studio 2010? Well, you got it. During the process that generates the Reference Guide, an XML file is created that has all the information to point Visual Studio in the right direction. You can download this ZIP file, extract the XML file into the AutoCAD Civil 3D 2013 installation folder (usually, "C:\Program Files\Autodesk\AutoCAD Civil 3D 2013"), and restart Visual Studio, if needed, and you will get help information for each of the API classes, methods, and properties right in your Visual Studio tool-tips as you type the code. Isn't that a dream come true?

What Else is Coming Up?

I recognize that for some of you local documentation is important. We are in the process of making the documentation available for download. We are looking at different alternatives because we want to have the same flexibility to update the downloads as we do with the on-line documentation. In the near future, I will update this post to provide links to the hosted files, so you can download, not only the Developer's Guide and Reference Guide, but also all the samples (as working code) included and embedded in the Reference Guide.

As you can see, we did a lot of work to bring you as much help as possible. There is still room for improvements, but we are at a point where changes can be easily propagated, which will allow us to provide a better service in the future. I think we are moving in the right direction, and I hope you participate in the process by telling us what more can we do to help you.

Update: Documentation Available for Download

As promised, we have made the new documentation available for download. You can access it now, and please report any problems with the links below.

Reference Guide. The ZIP file contains the entire Reference Guide in HTML format. You can extract the files and create a shortcut to index.html for quick access.

Developer's Guide. We have also provided a PDF with all the articles in the Developer’s Guide. We’ve found some formatting issues with certain images caused by the new documentation system in use by the User Experience group. They are investigating the problems, so please have a little patience. Still, the Developer’s Guide is full of great information, and this PDF should allow you to bring it with you everywhere.

Reference Guide Samples. All the Reference Guide samples are also available for download. This download contains a Visual Studio 2010 solution and projects with working code written in C# and VB.NET. As more samples become available, we will update this file, so you can download it and play with it.

Visual Studio Help Index. This download is a great resource. Extract and copy the included file into your Civil 3D installation directory, and Visual Studio will show you documentation information as tool-tips right from the Reference Guide.

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.

DevCamp 2012 Coming in June

Every two years ADN brings their DevCamp conferences to the States. DevCamp is a conference targeted to developers and enthusiasts who integrate and extend our platform technologies. Of a smaller size, DevCamp is like AU for developers, but being smaller allows more time to interact and meet with the people you care about.

This year, ADN is planning  two events in June. The first one is the AEC Developer Camp running June 6-7 in Waltham (near by Boston). Registration for this event is open, and you can get early-bird discounts if you register soon. The complete list of classes is available for download, and I am sure you will find very interesting ones. I will be attending this event, so I hope to see you there and have the chance to meet and talk for a while.

There will be a Manufacturing Developer Camp hosted June 13-14 in Portland OR. Registration is also open for this event, and you can also get early-bird discounts. You can download the complete list of classes and see if you are interested in any of the great classes being offered. I will not be attending this event, but it is a great opportunity to meet other members of the Autodesk engineering team and other colleagues.

ADN puts a lot of effort into DevCamp to provide a great learning experience for developers integrating with Autodesk products, and it is a great opportunity for the Autodesk engineering team to meet with our customers. Certainly, and opportunity you do not want to pass.

21WOJP – Week 1 - Migrating Your COM Code

With every new release, we revision the object version of the COM API. This is done for side-by-side compatibility and requires small updates to client code. Hopefully, your code using the COM API is well centralized, so the changes are easily located and simple to do. The new version of the COM API is 10.0, which means you will see the following changes.

The TLB files are installed into their own directory inside of Autodesk Shared using the COM version to separate type libraries of different releases. In the case of Jay Peak, the location is "C:\Program File\Common Files\Autodesk Shared\Civil Engineering 100". When updating your references, you should be able to use Visual Studio's "Add Reference" dialog. The COM tab will show the references referring to "Autodesk Civil Engineering ..." libraries. The following screen-shot show the references for Jay Peak (Civil 3D 2013).

The COM interops are no longer installed to the Global Assembly Cache (GAC), which means you need to add references to the interops from the AutoCAD Civil 3D installation directory, typically “C:\Program Files\Autodesk\AutoCAD Civil 3D 2013”. You can still see the references in the COM tab, and they work on my development environment because we register things different than production, but in a release environment adding the references from the COM tab will not work, and you will not be able to build your application (thanks to Jeff Mishler for pointing this detail, which I completely forgot).

Once you have updated your referenced assemblies, you need to update any place in code where you are creating/accessing objects by version. Usually, you would do that when accessing an application instance. A very common example is when accessing the Civil 3D Land Application object, which in Civil 3D 2012 you used the string "AeccXUiLand.AeccApplication.9.0". This string should be updated to "AeccXUiLand.AeccApplication.10.0".

There is no new functionality in the COM API, and your code should work with 2013 as it did with 2012. If you find any issues after you port your application, you should report them through the usual channels provided by ADN. You can also drop me a comment in this blog, and I will make sure the engineering team takes a look at the problem.