Navigating Through the Corridor Using

AutoCAD® Civil 3D® .NET API Augusto Goncalves - Autodesk

CP4887 Corridor is one of the most complex objects in the AutoCAD Civil 3D family of objects.

Working on a corridor object requires a clear understanding of its constituent components and their behavior. This class will give you an overview of corridor and associated objects and highlight how to access and extract useful details using the AutoCAD Civil 3D .NET API. Attendees must have a basic understanding of .NET programming concepts.

Learning Objectives At the end of this class, you will be able to:

Describe the corridor object and its constituents

Access and export the feature lines and other useful data

Access the applied assemblies and subassemblies to a corridor using .NET API

About the Speaker

Augusto Gonçalves is a DevTech engineer from Autodesk, based in São Paulo, Brazil. With five years of

previous experience before joining Autodesk, he has started supporting developers on AutoCAD®, Civil

3D®, Revit and Inventor based technologies, especially in Latin America. Augusto holds a Master's in

Computer Science and B.S. in Civil Engineering.

augusto.goncalves@autodesk.com

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

2

Introduction In my role as an API consultant I have had opportunities to help ADN partners in many Civil 3D® customization cases, especially regarding Reports and Custom Subassemblies. For this class I have collected and organized the basic information you need to start and export interesting data from Corridors. There are five main topics:

A general overview

Steps to start a Civil 3D® plug-in

Corridor Data Model

Exporting data (Create a Report)

Further reading

Overview

To develop for Civil 3D® we need Visual Studio, which according to Microsoft “is a comprehensive suite of tools designed to help software developers create innovative, next-generation applications. It’s the perfect work environment for application developers”. There are different versions of this IDE, each one for each type of development environment and you can choose the one that best fit your needs.

Fortunately there is a free version called Express Edition. This version allows you to write and compile VB.NET or C# project with almost all IDE resources available as the full version. It is important to remember that all versions of Visual Studio, including Express Edition, require permissions to install it on your machine.

At this class will be used Visual Basic Express Edition, used to write and compile VB.NET code. VB.NET is a true object-oriented language; which means that some unintuitive and inconsistent features like GoSub/Return and DefInt have been removed from the language. For more information and how to download, please visit the following link http://www.microsoft.com/express/

It is possible developer for Civil 3D® using VBA, but after Microsoft announced the “Discontinuation of the VBA Licensing Program” (see http://msdn.microsoft.com/en-us/isv/bb190538.aspx) on July 2007, Autodesk marked the ActiveX API (used by VBA) as deprecated. It possible use this API with VB.NET, which can be handy where the .NET is not implemented yet.

Now back to Visual Basic .NET, the first release of the .NET API was with Civil 3D® 2009, and it is evolving every year. As this API is deeply integrated with Microsoft .NET framework, we have access to many others APIs, including WinForms, ADO.NET and the AutoCAD.NET API.

Getting Started The following is a step by step example that creates a simple project for Civil 3D® .NET Plug-in. If you are familiar with that you can skip to the next Topic, Corridor Data Model. If this is your first time, consider take a AutoCAD .NET API training or watch our DevTV: Introduction to AutoCAD .NET Programming.

1. Start Microsoft Visual Basic Express Edition. Check if the application starts with (Administrator) on the title bar. If not, you may have to change your Windows Credentials to have this privilege.

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

3

This is not mandatory, just recommended, see more info at MSDN (http://msdn.microsoft.com/en-us/library/ms165100.aspx).

2. Go to menu File, and then select New Project. Here you have to select Class Library, which will produce a .dll file that you can load inside Civil 3D® and register new commands. Name the project as CorridorReport, for instance.

Important: For Civil 3D 2010/2011 you need to use Visual Basic 2008 (.NET 3.5). For Civil 3D 2012 you need to use Visual Basic 2010 (.NET 4.0). That is the default configuration.

3. Now, at the Solution Explorer window, right click on CorridorReport project and then select Add Reference. It is also possible go to project properties, select the “References” tab and click on “Add” and select “Reference”. Tip: If this window does not appear on your VS IDE, go to menu View, and select Solution Explorer, or simply press Ctrl+Alt+L.

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

4

4. A plug-in project needs to reference the main application in order to communicate with it. For a Civil 3D® .NET Addin we need four references, all from the installation folder:

AcMgd: AutoCAD Interface resources

AcDbMdg: AutoCAD Database resources

AecBaseMgd: Aec Base resources for Civil 3D®, also shared with other products

AeccDbMgd: Civil 3D® Database specific resources

5. It is very important mark all references as Copy Local equals FALSE. To do so, again at the Solution Explorer, right click at the project name and go to Properties, then go to References tab, select the references just added, go to Properties and mark as False at Copy Local field.

Important: the references above are for 2011, but same apply to all versions with .NET API. Tip: If you left the references with Copy Local equals True, it is likely to get the following error message when starting Civil 3D® (or AutoCAD®) in debug mode. To fix it, just set Copy Local equals False.

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

5

The above steps are required for all new addin projects for Civil 3D®. Now with this project ready, let’s start writing some code. The following is a step by step example that creates a simple command to show the number of corridors.

1. New VB.NET projects usually came with a Class1.vb file, which contains a Class1 definition. A custom command requires a new regular VB.NET routine. As this sub routine will be our command, it must be Public and a Sub.

Public Class Class1

Public Sub CountCorridors()

End Sub

End Class

2. To use AutoCAD® and Civil 3D® API features we can either use the full qualified name or import the namespaces. The second is usually better as keep us from typing the entire name every time, i.e. save long typing. The following namespaces are usually needed to start:

Imports Autodesk.AutoCAD.Runtime

Imports Autodesk.AutoCAD.ApplicationServices

Imports Autodesk.AutoCAD.EditorInput

Imports Autodesk.Civil.ApplicationServices

Public Class Class1

Public Sub CountCorridors()

End Sub

End Class

3. Now in order to make this sub routine execute as a command we can append an attribute to it, like below (the namespace piece was omitted for brevity). Notice that the name inside CommandMethod will be used to invoke the CountCorridors sub routine inside Civil 3D®. These

names are not required to be equal, like in this sample.

Public Class Class1

<CommandMethod("countCorridors")> _

Public Sub CountCorridors()

End Sub

End Class

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

6

4. Usually a command that has user interactions through command line (AutoCAD® prompt) need to access the active Editor object (i.e. AutoCAD® Editor). Additionally for Civil 3D® command it is also useful access the active CivilDocument. This is a common “command header” for Civil 3D® custom commands.

<CommandMethod("countCorridos")> _

Public Sub CountCorridors()

'access AutoCAD Editor

Dim ed As Editor = Application.DocumentManager.MdiActiveDocument.Editor

'access Civil Document

Dim civilDoc As CivilDocument = CivilApplication.ActiveDocument

End Sub

5. Finally the CivilDocument gives us access to the collection of Corridors. One important thing here is that AutoCAD®, and therefore Civil 3D®, store information on its database using ObjectId as keys to access the information. In this sample, we actually access the list of Corridors ObjectIds. We will come back to ObjectIds later.

<CommandMethod("countNets")> _

Public Sub CountCorridors()

'access AutoCAD Editor

Dim ed As Editor = Application.DocumentManager.MdiActiveDocument.Editor

'access Civil Document

Dim civilDoc As CivilDocument = CivilApplication.ActiveDocument

'show the number of corridors

ed.WriteMessage("Document contains {0} corridors", _

civilDoc.CorridorCollection.Count)

End Sub

With Editor.WriteMessage method is possible pass information to include at the message. To do so we write the parameter number – e.g. {0} – somewhere inside the message, then pass the parameters. The message will be formatted with all parameters, starting at 0 (zero).

Tip: In VB.NET we can use the underscore sign “_” to indicate that one line of line start at one line and end at the following, but have no effect on how the code is executed – it is merely visual and handy when we have long lines of code. This was used at the above code.

Corridor Data Model Each object on Civil 3D® have a lot of properties, which is the data immediate accessible to us. All properties are listed on the help file, which is offline (CHM file) until 2011 and online after 2012. I will not copy & paste the entire help file, so for 2011 and previous versions open the CHM help file at the install folder <<Civil 3D folder>>\Help\civil_api_net_reference.chm or for 2012 visit the online documentation at http://docs.autodesk.com/CIV3D/2012/ENU/API_Reference_Guide/index.html. For both cases, select the object on the list, then at the bottom select “Properties”.

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

7

Although all the properties are listed on the documentation, some are worth mentioning. The image below illustrates this. The corridor contains a collection of baselines. Each baseline can have its own Alignment and Profile, therefore are properties to access the respective ObjectIds. At this point the Corridor API starts merging with other APIs, i.e. Alignment and Profile. Following, the baseline contains a collection of baseline regions, which contains a collection of Applied Assemblies, which contains its own information (e.g. Links, Points, and Shapes) point to the original Assembly. As expected, the applied assembly contains a collection of Applied Subassemblies, which points to the original Subassembly and other data, such as a XYZ coordinate data called OriginStationOffsetElevationToBaseline (a single object with 3 important information: station, offset and elevation).

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

8

To access the described data model we (usually) need to access objects hierarchy. It is possible go directly to the bottom of above chart, but is often not useful as we lost the ownership. Anyway, suppose we need to list them all, the pseudo-code below demonstrate how go deep on this hierarchy. Note that each iteration (VB.NET for each or C# foreach) is for the specific owner context, meaning the applied subassemblies are for the current assembly on the loop, which therefore for the current baseline on the loop, and so forth. Suppose we want all subassemblies of a Corridor, we need to collect them all together.

Sub ListAll() ' open the corridor object Dim corridor As Corridor ' iterate through each baseline For Each baseline In corridor.Baselines ' go through each baseline region For Each baselineRegion In baseline.BaselineRegions ' now each applied assembly For Each appliedAssembly In baselineRegion.AppliedAssemblies ' finally each applied subassembly For Each AppliedSubassembly In appliedAssembly.GetAppliedSubassemblies Next Next Next Next End Sub Due time constraint, this class will not cover the related objects, like Alignment, Profile or Surface. Please visit our Civil 3D® Developer Center at www.autodesk.com/developcivil for more information on other APIs, including a webcast on Surface API. Also, consider attend or review the class CP4321: Understanding the Alignments and Profiles API in AutoCAD® Civil 3D®.

Initially for this class, I have developed a tool that proved to be useful for the entire API: Snoop Civil 3D® Database. Both binary and source-code are available Civilized Development blog, or at the Developer Center. The data model presented here can be visualized with the current drawing data.

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

9

Some Civil 3D® object, like Subassemblies, store information under parameters. It can contain collection of parameter per object type, e.g. ParamsDouble, ParamsString. Again, use the Snoop Database tool to inspect the parameters, there are several of them for each type of subassembly. This is connected to how we create a subassembly. The image below show how access a parameter using the snoop tool.

Tip: the localized values DisplayName and Description on the Subassembly parameters are stored at a

resource DLL at Civil 3D® folder: AeccStockSubassemblyScriptsRC.dll.

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

10

Applicable Sample: Creating a Corridor Report For this sample we will use Microsoft® Excel®, which must be installed. Although some knowledge on this API is important, this part of the class will use a “connector” custom VB.NET class to avoid dealing with Excel® API methods. That way we don’t need to worry about another API for now. Feel free to expand or use on your own projects.

Our goal is to create a list of subassemblies on a Civil 3D® Corridor and export them per station to an Excel® file. A full report will possibly include more information, such as the relationship with Alignments and Surfaces, but will not be covered here. All left assemblies will be listed first, then the center, finally the right subassemblies. The image below illustrates the result we seek.

The first step is collecting all applied subassemblies. To do so, we need to implement the pseudo-code presented before that will run through all baselines, then baseline regions, then applied assemblies, which finally contain the applied subassemblies. The sample project of this class contains this method, check ReportGenerator.vb. Below is this method. Notice that all applied subassemblies are stored on the list. For now we are not considering where they are applied.

Private appSubassemblies As List(Of AppliedSubassembly) Private Sub ListAppliedSubassemblies() ' create the list appSubassemblies = New List(Of AppliedSubassembly) ' iterate through each baseline For Each bline As Baseline In cor.Baselines ' go through each baseline region For Each bLineRetion As BaselineRegion In bline.BaselineRegions ' now each applied assembly For Each appAss As AppliedAssembly In bLineRetion.AppliedAssemblies ' add the applied SAs to the list appSubassemblies.AddRange(appAss.GetAppliedSubassemblies()) Next Next Next End Sub Now we need to order the applied subassemblies by station and by offset. On Civil 3D®, subassemblies on the left have offset <1 (negative), >1 (positive) on the right and 0 (zero) on the center. If you record from Data Model Topic, the AppliedSubassembly have a single property to store the station and the

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

11

offset, OriginStationOffsetElevationToBaseline, where X is the station, Y is the offset and Z is the elevation from the baseline. There is a Framework .NET API called Linq (visit MSDN for more information), which allow us perform SQL-like operations on collections (e.g. List). So here we need to sort ascending by station and by offset. Cool isn’t it?

' sort the list of applied subassemblies ' order by station ' order by offset (from left, to center, to right) Dim appSubassOrder As Object = _ From appSubass In appSubassemblies Order By appSubass.OriginStationOffsetElevationToBaseline.X, appSubass.OriginStationOffsetElevationToBaseline.Y Ascending Select appSubass The data we need is almost complete, still missing the Slope parameter. Again back to the end of Data Model Topic we saw how access parameters of subassemblies. Using the snoop tool we can notice that the slope parameter is stored under TypeInfo.TransparentCmdSlope, but we can find two of those, but let’s use the Input Access type (not the Output, i.e. read-only). The function below, that is also on the sample project of this class, iterate through the collection of double parameters and get the one that meets our criteria (info type and access type).

Private Function GetSlopeParam(ByVal subass As Subassembly) As Double For Each paramDouble As ParamDouble In subass.ParamsDouble If (paramDouble.TypeInfo = TypeInfoDouble.TransparentCmdSlope _ And paramDouble.Access = ParamAccessType.Input) Then Return paramDouble.Value ' found it! Return its value End If Next Return 0 ' no parameter, return zero End Function Now we have all the corridor data required for this sample report. The missing piece is the Elevation at the center line from the reference surface. For that we need Surface API, more specifically call FindElevationAtXY from the Surface or CorridorSurface object. The corridor surface collection is accessible from the Corridor object. Due time constraint we will not cover this topic here.

Finally it is time to write on Excel®. The ExcelConector.vb sample-code make our life really easy. Create the object and the application will launch, then call its Write method passing the column (A, B, C, etc), the row (1, 2, 3, etc) and the value to write. The sample function GenerateReport at ReportGenerator.vb

sample does that, take a look.

Further Reading Some classes you might want to attend:

CP4321: Understanding the Alignments and Profiles API in AutoCAD® Civil 3D®

CP9222-U: Improving the Usability of the AutoCAD® Civil 3D® API

CI6401-P: Corridor Deconstruction

Navigating Through the Corridor Using AutoCAD® Civil 3D® .NET API

12

Also, some useful Civil 3D® online material:

Civilized Development blog - http://civilizeddevelopment.typepad.com

Isaac Rodrigues’s Civil 3D API focused blog includes several example codes for .NET

Civil 3D® Online help – http://docs.autodesk.com/CIV3D/2012/ENU/API_Reference_Guide

Documentation of the entire API

Civil 3D® Developers Center – http://www.autodesk.com/developcivil

Training material, recorded presentations and tools.

Discussion Groups - http://forums.autodesk.com/t5/AutoCAD-Civil-3D-Customization/bd-p/190

Information about the Autodesk Developer Network – http://www.autodesk.com/joinadn

ADN members can ask unlimited API questions through our DevHelp Online interface

API Training – http://www.autodesk.com/apitraining

Information about upcoming training classes and webcasts, also download of webcasts

Watch out for our regular ADN DevLab events. DevLab is a programmers’ workshop (free to ADN

and non-ADN members) where you can come and discuss your AutoCAD programming problems

with the ADN DevTech team.

Conclusion Thank you for attending this session on Civil 3D® Corridor .NET API. I hope you found the class

enjoyable and valuable. In this handout I have presented information that will be very helpful when

redoing the same with many “tips” and “important” information strategically located where make more

sense.

You have seen how start a .NET plug-in for Civil 3D® from scratch. As you may have notice, this is quite

similar to AutoCAD .NET plug-in. After that, we reviewed the data model of corridors, from the main object

up to the bottom object, applied subassembly. Finally we used that information to create a basic Excel®

report, which you can further expand to your needs.

I am glad you are considering explore Civil 3D® API, specially Corridors API, to improve your company

workflow or develop applications, there is a lot more to learn out there, do not stop here. Good luck and

success on your work.