Civilized Development

Alignment Entities Encapsulated

In previous posts, we have been looking at the ‘AlignmentEntityCollection’ class and how to use the alignment entity objects. We found a couple of areas where the use of the API was not intuitive. We saw how, by default, the ‘AlignmentEntityCollection’ enumerates entities by the ‘EntityId’, which may or may not be the order of the entities within the alignment. We also saw how the ‘AlignmentEntity’ class type does not indicate the type of entity, and how classes are reused for different entity types.We explained how the correct way to identify an ‘AlignmentEntity’ type is evaluating its ‘EntityType’ property, as opposed to its class type. Today, we will look at ways to adapt the design to provide a different interface, which may be more suited for certain requirements.

Tell, Don’t Ask

One of the problems with the ‘AlignmentEntity’ class hierarchy is that it violates an important Object Oriented Design principle “Tell, Don’t Ask’. “Tell, Don’t Ask” is a principle, which prefers that an ‘objectA’ tells an ‘objectB’ to do something, rather than query its state and make a decision on what to do. Many API’s violate this principle for a very simple reason; they want to expose as much information as possible to insure users can implement their own processes and extend the functionality. The results are API’s that are hard to use because users need to understand the details of the implementation and client code full of conditional statements trying to figure out what API objects can do.

The ‘Adapter Pattern’ is used to convert the interface of a class/system into a different interface that adapts to the client needs.We will start by adapting the current Civil 3D API interface to a design that removes the need to ask the entities for their type. To achieve this goal, we define a base class ‘AAlignmentEntity’ (the first ‘A’ indicates that the class is abstract), and we derive entity classes from it. The following diagram shows the design.

The diagram does not show all the classes in the hierarchy, but you get the idea. We will implement an alignment entity adapter for each alignment entity type. Common functionality will be implemented in the base class ‘AAlignmentEntity’.

C#

/// <summary>
/// Abstract base class for all alignment entities.
/// </summary>
/// <para>
/// This class serves as a wrapper for alignment entity objects.
/// The class it self is abstract so it cannot be instantiated,
/// but sub classes must provide the wrapped entity, which will
/// be managed in this class.
/// </para>
public abstract class AAlignmentEntity
{
    internal AAlignmentEntity()
    {
        m_TheEntity = null;
    }
    /// <summary>
    /// Returns whether the wrapper entity is valid (has been assigned).
    /// </summary>
    public bool IsValid
    {
        get { return m_TheEntity != null; }
    }
    /// <summary>
    /// Writes the alignment entity information to the specified writer.
    /// </summary>
    /// <param name="writer">Writer to which write the inforamtion.</param>
    public void WriteInfo(IAlignmentEntityInfoWriter writer)
    {
        writeCommonInfo(writer);
        WriteCustomInfo(writer);
        writer.EntityInfoDone();
    }
    /// <summary>
    /// Assigns the wrapped entity.
    /// </summary>
    /// <param name="entity">Entity to wrap.</param>
    internal void AssignEntity(AlignmentEntity entity)
    {
        m_TheEntity = entity;
    }
    /// <summary>
    /// This method must be implemented in derived classes to write
    /// the custom entity information.
    /// </summary>
    /// <param name="writer"></param>
    protected abstract void WriteCustomInfo(
        IAlignmentEntityInfoWriter writer);
    private void writeCommonInfo(IAlignmentEntityInfoWriter writer)
    {
        writer.WriteEntityId(m_TheEntity.EntityId);
        writer.WriteWrappedEntityClassType(m_TheEntity.GetType());
        writer.WriteSubEntityCount(m_TheEntity.SubEntityCount);
    }
    private AlignmentEntity m_TheEntity;
}

VB.NET

''' <summary>
''' Abstract base class for all alignment entities.
''' </summary>
''' <para>
''' This class serves as a wrapper for alignment entity objects.
''' The class it self is abstract so it cannot be instantiated,
''' but sub classes must provide the wrapped entity, which will
''' be managed in this class.
''' </para>
Public MustInherit Class AAlignmentEntity
  Friend Sub New()
    m_TheEntity = Nothing
  End Sub
  ''' <summary>
  ''' Returns whether the wrapper entity is valid (has been assigned).
  ''' </summary>
  Public ReadOnly Property IsValid() As Boolean
    Get
      Return m_TheEntity IsNot Nothing
    End Get
  End Property
  ''' <summary>
  ''' Writes the alignment entity information to the specified writer.
  ''' </summary>
  ''' <param name="writer">Writer to which write the inforamtion.</param>
  Public Sub WriteInfo(writer As IAlignmentEntityInfoWriter)
    writeCommonInfo(writer)
    WriteCustomInfo(writer)
    writer.EntityInfoDone()
  End Sub
  ''' <summary>
  ''' Assigns the wrapped entity.
  ''' </summary>
  ''' <param name="entity">Entity to wrap.</param>
  Friend Sub AssignEntity(entity As AlignmentEntity)
    m_TheEntity = entity
  End Sub
  ''' <summary>
  ''' This method must be implemented in derived classes to write
  ''' the custom entity information.
  ''' </summary>
  ''' <param name="writer"></param>
  Protected MustOverride Sub WriteCustomInfo( _
    writer As IAlignmentEntityInfoWriter)
  Private Sub writeCommonInfo(writer As IAlignmentEntityInfoWriter)
    writer.WriteEntityId(m_TheEntity.EntityId)
    writer.WriteWrappedEntityClassType(m_TheEntity.[GetType]())
    writer.WriteSubEntityCount(m_TheEntity.SubEntityCount)
  End Sub
  Private m_TheEntity As AlignmentEntity
End Class

The ‘AAlignmentEntity’ class declares a ‘WriteInfo()’ method that we will use to display the information about each entities in an ‘Alignment’. The implementation calls ‘writeCommonInfo()’, which will write the common information, and then calls ‘WriteCustomInfo()’, which is a protected abstract method that derived classes must implement to write any custom information. Here is a sample implementation in a derived entity class.

C#

protected override void WriteCustomInfo(
    IAlignmentEntityInfoWriter writer)
{
    writer.WriteCurveGroupName("Line");
}

VB.NET

Protected Overrides Sub WriteCustomInfo( _
    writer As IAlignmentEntityInfoWriter)
  writer.WriteCurveGroupName("Line")
End Sub

Centralizing Conditional Code

Violating the “Tell, Don’t Ask” principle causes a “conditional mess” in client code. That happens when our code constantly queries objects to verify their state. The code ends up full of ‘if/else’ and ‘switch’ statements and becomes hard to follow. Our adapters will help us with that, but we still need conditional code to decide what entity adapter we should create. The ‘Factory Method Pattern’ can help us achieve this goal. There are different ways to implement ‘Factory Method’, but I like to extract the logic into a separate factory class.

C#

/// <summary>
/// Factory class that creates the wrapping adapters for alignment
/// entity objects.
/// </summary>
internal class AlignmentEntityWrapperFactory
{
    /// <summary>
    /// Creates an AAlignmentEntity wraping an alignment entity.
    /// </summary>
    /// <param name="entity">Entity to be wrapped.</param>
    /// <returns>A wrapper AAlignmentEntity object.</returns>
    public static AAlignmentEntity WrapEntity(AlignmentEntity entity)
    {
        AAlignmentEntity wrapped = CreateWrapper(entity.EntityType);
        wrapped.AssignEntity(entity);
        return wrapped;
    }
    /// <summary>
    /// Factory method that creates the correct wrapper for a specified
    /// entity type.
    /// </summary>
    /// <remarks>
    /// This method was provided to be able to test the correct wrapper
    /// class is created for all supported entity types. Users should
    /// not call this method directly because it returns an empty
    /// wrapper. Instead, users should call WrapEntity(), which
    /// initializes the wrapper after is created.
    /// </remarks>
    /// <param name="type"></param>
    /// <returns></returns>
    internal static AAlignmentEntity CreateWrapper(AlignmentEntityType type)
    {
        switch(type)
        {
            case AlignmentEntityType.Line:
                return new AlignmentEntityLine();
            case AlignmentEntityType.Arc:
                return new AlignmentEntityCurve();
                    
            case AlignmentEntityType.Spiral:
                return new AlignmentEntitySpiral();
            case AlignmentEntityType.SpiralCurveSpiral:
                return new AlignmentEntitySCS();
            case AlignmentEntityType.SpiralLineSpiral:
                return new AlignmentEntitySLS();
            case AlignmentEntityType.SpiralLine:
                return new AlignmentEntitySL();
            case AlignmentEntityType.LineSpiral:
                return new AlignmentEntityLS();
            case AlignmentEntityType.SpiralCurve:
                return new AlignmentEntitySC();
            case AlignmentEntityType.CurveSpiral:
                return new AlignmentEntityCS();
            case AlignmentEntityType.SpiralSpiralCurveSpiralSpiral:
                return new AlignmentEntitySSCSS();
            case AlignmentEntityType.SpiralCurveSpiralCurveSpiral:
                return new AlignmentEntitySCSCS();
            case AlignmentEntityType.SpiralCurveSpiralSpiralCurveSpiral:
                return new AlignmentEntitySCSSCS();
            case AlignmentEntityType.SpiralSpiral:
                return new AlignmentEntitySS();
            case AlignmentEntityType.SpiralSpiralCurve:
                return new AlignmentEntitySSC();
            case AlignmentEntityType.CurveSpiralSpiral:
                return new AlignmentEntityCSS();
            // Not used for now.
            // case AlignmentEntityType.MultipleSegments:
            // 
            case AlignmentEntityType.CurveLineCurve:
                return new AlignmentEntityCLC();
            case AlignmentEntityType.CurveReverseCurve:
                return new AlignmentEntityCRC();
            case AlignmentEntityType.CurveCurveReverseCurve:
                return new AlignmentEntityCCRC();
            default:
                throw new NotImplementedException(
                    "Specified entity wrapper not implemented.");
        }
    }
}

VB.NET

Friend Class AlignmentEntityWrapperFactory
  ''' <summary>
  ''' Creates an AAlignmentEntity wraping an alignment entity.
  ''' </summary>
  ''' <param name="entity">Entity to be wrapped.</param>
  ''' <returns>A wrapper AAlignmentEntity object.</returns>
  Public Shared Function WrapEntity(entity As AlignmentEntity) _ 
      As AAlignmentEntity
    Dim wrapped As AAlignmentEntity = CreateWrapper(entity.EntityType)
      wrapped.AssignEntity(entity)
      Return wrapped
    End Function
  ''' <summary>
  ''' Factory method that creates the correct wrapper for a specified
  ''' entity type.
  ''' </summary>
  ''' <remarks>
  ''' This method was provided to be able to test the correct wrapper
  ''' class is created for all supported entity types. Users should
  ''' not call this method directly because it returns an empty
  ''' wrapper. Instead, users should call WrapEntity(), which
  ''' initializes the wrapper after is created.
  ''' </remarks>
  ''' <param name="type"></param>
  ''' <returns></returns>
  Friend Shared Function CreateWrapper(type As AlignmentEntityType) _
      As AAlignmentEntity
    Select Case type
      Case AlignmentEntityType.Line
        Return New AlignmentEntityLine()
      Case AlignmentEntityType.Arc
        Return New AlignmentEntityCurve()
      Case AlignmentEntityType.Spiral
        Return New AlignmentEntitySpiral()
      Case AlignmentEntityType.SpiralCurveSpiral
        Return New AlignmentEntitySCS()
      Case AlignmentEntityType.SpiralLineSpiral
        Return New AlignmentEntitySLS()
      Case AlignmentEntityType.SpiralLine
        Return New AlignmentEntitySL()
      Case AlignmentEntityType.LineSpiral
        Return New AlignmentEntityLS()
      Case AlignmentEntityType.SpiralCurve
        Return New AlignmentEntitySC()
      Case AlignmentEntityType.CurveSpiral
        Return New AlignmentEntityCS()
      Case AlignmentEntityType.SpiralSpiralCurveSpiralSpiral
        Return New AlignmentEntitySSCSS()
      Case AlignmentEntityType.SpiralCurveSpiralCurveSpiral
        Return New AlignmentEntitySCSCS()
      Case AlignmentEntityType.SpiralCurveSpiralSpiralCurveSpiral
        Return New AlignmentEntitySCSSCS()
      Case AlignmentEntityType.SpiralSpiral
        Return New AlignmentEntitySS()
      Case AlignmentEntityType.SpiralSpiralCurve
        Return New AlignmentEntitySSC()
      Case AlignmentEntityType.CurveSpiralSpiral
        Return New AlignmentEntityCSS()
      ' Not used for now.
      ' case AlignmentEntityType.MultipleSegments:
      ' 
      Case AlignmentEntityType.CurveLineCurve
        Return New AlignmentEntityCLC()
      Case AlignmentEntityType.CurveReverseCurve
        Return New AlignmentEntityCRC()
      Case AlignmentEntityType.CurveCurveReverseCurve
        Return New AlignmentEntityCCRC()
      Case Else
        Throw New NotImplementedException(
          "Specified entity wrapper not implemented.")
    End Select
  End Function
End Class

The ‘AlignmentEntityWrapperFactory’ class responsibility is to create the entity adapters and initialize them using the underlying entity from the Civil 3D API.

Processing Alignment Entities

As we have seen in a previous post, There are different ways to iterate through the alignment entities. In our samples, we saw how by default the ‘AlignmentEntityCollection’ iterated through the entities in the order they were created and added to the alignment, but we could also use the ‘GetEntityByOrder()’ method to iterate from the beginning of the alignment to the end. In our sample commands, we want to iterate through the entities and display information about them. In the future, we may want to add other functionality that involves iterating through the entities, so we are going to implement an ‘AlignmentEntityProcessor’ class that will provide methods to do the processing. Since there are different ways to iterate through the entities and we want the flexibility to change the behavior, we will use the ‘Strategy Pattern’ to customize how we iterate through them.

The ‘Strategy Pattern’ encapsulates an object behavior, in our case the iteration through the alignment entities, into a policy set of classes, so the behavior can be modified by assigning a different policy. The ‘IAlignmentEntityEnumerationPolicy’ interface defines the policy. This interface implements ‘IEnumerable (of AAlignmentEntity)’, which provides the interface to iterate through the entities.

C#

public interface IAlignmentEntityEnumerationPolicy : 
    IEnumerable<AAlignmentEntity>
{
    void Initialize(AlignmentEntityCollection entities);
}

VB.NET

Public Interface IAlignmentEntityEnumerationPolicy
    Inherits IEnumerable(Of AAlignmentEntity)
  Sub Initialize(entities As AlignmentEntityCollection)
End Interface

We provide two implementations of the “IAlignmentEntityEnumerationPolicy’ interface. The first one; ‘ByEntityIdEnumerationPolicy’ iterates through the entities in order of creation (of ID).

C#

/// <summary>
/// Enumeration policy that enumerates the alignment entities by
/// order of ID.
/// </summary>
public class ByEntityIdEnumerationPolicy : IAlignmentEntityEnumerationPolicy
{
    /// <summary>
    /// Initializes the policy object with the current entity collection
    /// for the alignment.
    /// </summary>
    /// <param name="entities">Entities to enunmerate.</param>
    public void Initialize(AlignmentEntityCollection entities)
    {
        m_TheEntities = entities;
    }
    /// <summary>
    /// Returns an alignment entity enumerator.
    /// </summary>
    /// <returns>Returns the enumerator object.</returns>
    public IEnumerator<AAlignmentEntity> GetEnumerator()
    {
        return new ByEntityIdEnumerator(m_TheEntities);
    }
    /// <summary>
    /// Returns an alignment entity enumerator.
    /// </summary>
    /// <returns>Returns the enumerator object.</returns>
    System.Collections.IEnumerator 
        System.Collections.IEnumerable.GetEnumerator()
    {
        return new ByEntityIdEnumerator(m_TheEntities);
    }
    private AlignmentEntityCollection m_TheEntities;
 }
/// <summary>
/// Enumerator object that enumerates entities by ID order.
/// </summary>
public class ByEntityIdEnumerator : IEnumerator<AAlignmentEntity>
{
    /// <summary>
    /// Initialzies the enumerator using the entity collection.
    /// </summary>
    /// <param name="entities">Alignment entity collection to enumerate.
    /// </param>
    internal ByEntityIdEnumerator(AlignmentEntityCollection entities)
    {
        m_TheEntities = entities;
        m_Enumerator = m_TheEntities.GetEnumerator();
    }
    /// <summary>
    /// Returns the current entity.
    /// </summary>
    public AAlignmentEntity Current
    {
        get {
            return AlignmentEntityWrapperFactory.WrapEntity(
                m_Enumerator.Current);
        }
    }
    /// <summary>
    /// Disposes the object.
    /// </summary>
    public void Dispose()
    {
        m_Enumerator.Dispose();
        m_TheEntities.Dispose();
    }
    /// <summary>
    /// Returns the current entity as an object.
    /// </summary>
    object System.Collections.IEnumerator.Current
    {
        get {
            return AlignmentEntityWrapperFactory.WrapEntity(
                m_Enumerator.Current);
        }
    }
    /// <summary>
    /// Moves to the next entity.
    /// </summary>
    /// <returns>Returns true if there is an entity left or false
    /// otherwise.</returns>
    public bool MoveNext()
    {
        return m_Enumerator.MoveNext();
    }
    /// <summary>
    /// Resets the enumerator.
    /// </summary>
    public void Reset()
    {
        m_Enumerator.Reset();
    }
    private AlignmentEntityCollection m_TheEntities;
    private IEnumerator<AlignmentEntity> m_Enumerator;
        
}

VB.NET

''' <summary>
''' Enumeration policy that enumerates the alignment entities by
''' order of ID.
''' </summary>
Public Class ByEntityIdEnumerationPolicy
    Implements IAlignmentEntityEnumerationPolicy
  ''' <summary>
  ''' Initializes the policy object with the current entity collection
  ''' for the alignment.
  ''' </summary>
  ''' <param name="entities">Entities to enunmerate.</param>
  Public Sub Initialize(entities As AlignmentEntityCollection) _
      Implements IAlignmentEntityEnumerationPolicy.Initialize
    m_TheEntities = entities
  End Sub
  ''' <summary>
  ''' Returns an alignment entity enumerator.
  ''' </summary>
  ''' <returns>Returns the enumerator object.</returns>
  Public Function GetEnumerator() As IEnumerator(Of AAlignmentEntity) _
      Implements IAlignmentEntityEnumerationPolicy.GetEnumerator
    Return New ByEntityIdEnumerator(m_TheEntities)
  End Function
  ''' <summary>
  ''' Returns an alignment entity enumerator.
  ''' </summary>
  ''' <returns>Returns the enumerator object.</returns>
  Private Function System_Collections_IEnumerable_GetEnumerator() _
      As System.Collections.IEnumerator _
      Implements System.Collections.IEnumerable.GetEnumerator
    Return New ByEntityIdEnumerator(m_TheEntities)
  End Function
  Private m_TheEntities As AlignmentEntityCollection
End Class
''' <summary>
''' Enumerator object that enumerates entities by ID order.
''' </summary>
Public Class ByEntityIdEnumerator
    Implements IEnumerator(Of AAlignmentEntity)
  ''' <summary>
  ''' Initialzies the enumerator using the entity collection.
  ''' </summary>
  ''' <param name="entities">Alignment entity collection to enumerate.
  ''' </param>
  Friend Sub New(entities As AlignmentEntityCollection)
    m_TheEntities = entities
    m_Enumerator = m_TheEntities.GetEnumerator()
  End Sub
  ''' <summary>
  ''' Returns the current entity.
  ''' </summary>
  Public ReadOnly Property Current() As AAlignmentEntity _
      Implements IEnumerator(Of AAlignmentEntity).Current
    Get
      Return AlignmentEntityWrapperFactory.WrapEntity( _
        m_Enumerator.Current)
    End Get
  End Property
  ''' <summary>
  ''' Disposes the object.
  ''' </summary>
  Public Sub Dispose() Implements IDisposable.Dispose
    m_Enumerator.Dispose()
    m_TheEntities.Dispose()
  End Sub
  ''' <summary>
  ''' Returns the current entity as an object.
  ''' </summary>
  Private ReadOnly Property System_Collections_IEnumerator_Current() _
      As Object Implements System.Collections.IEnumerator.Current
    Get
      Return AlignmentEntityWrapperFactory.WrapEntity( _
      m_Enumerator.Current)
    End Get
  End Property
  ''' <summary>
  ''' Moves to the next entity.
  ''' </summary>
  ''' <returns>Returns true if there is an entity left or false
  ''' otherwise.</returns>
  Public Function MoveNext() As Boolean _
      Implements System.Collections.IEnumerator.MoveNext
    Return m_Enumerator.MoveNext()
  End Function
  ''' <summary>
  ''' Resets the enumerator.
  ''' </summary>
  Public Sub Reset() Implements System.Collections.IEnumerator.Reset
    m_Enumerator.Reset()
  End Sub
  Private m_TheEntities As AlignmentEntityCollection
  Private m_Enumerator As IEnumerator(Of AlignmentEntity)
End Class

The implementation of ‘ByEntityIdEnumerationPolicy’ uses a ‘ByEntityIdEnumerator’ class that enumerates the entities in order of ID (or creation). The implementation of ‘BySequenceEnumerationPolicy’ is very similar; although, we will use ‘GetEntityByOrder()’ to access the entity.

C#

/// <summary>
/// Enumeration policy that enumerates the alignment entities by
/// sequence in the alignment.
/// </summary>
public class BySequenceEnumerationPolicy : IAlignmentEntityEnumerationPolicy
{
    /// <summary>
    /// Initializes the policy from the alignment entities.
    /// </summary>
    /// <param name="entities">Entities to enumerate.</param>
    public void Initialize(AlignmentEntityCollection entities)
    {
        m_TheEntities = entities;
    }
    /// <summary>
    /// Returns enumerator.
    /// </summary>
    /// <returns>Returns enumerator object.</returns>
    public IEnumerator<AAlignmentEntity> GetEnumerator()
    {
        return new BySequenceEnumerator(m_TheEntities);
    }
    /// <summary>
    /// Returns the enumerator.
    /// </summary>
    /// <returns>Returns enumerator object.</returns>
    System.Collections.IEnumerator 
        System.Collections.IEnumerable.GetEnumerator()
    {
        return new BySequenceEnumerator(m_TheEntities);
    }
    private AlignmentEntityCollection m_TheEntities;
}
/// <summary>
/// Enumerator object that enumerates the entities by sequence order.
/// </summary>
public class BySequenceEnumerator : IEnumerator<AAlignmentEntity>
{
    /// <summary>
    /// Initializes the class from the alignment entities.
    /// </summary>
    /// <param name="entities">Entities to enumerate</param>
    internal BySequenceEnumerator(AlignmentEntityCollection entities)
    {
        m_TheEntities = entities;
        m_EntityIndex = -1;
    }
    /// <summary>
    /// Returns the current entity.
    /// </summary>
    public AAlignmentEntity Current
    {
        get {
            AlignmentEntity entity = 
                m_TheEntities.GetEntityByOrder(m_EntityIndex);
            return AlignmentEntityWrapperFactory.WrapEntity(entity);
        }
    }
    /// <summary>
    /// Disposes the object.
    /// </summary>
    public void Dispose()
    {
        m_TheEntities = null;
        m_EntityIndex = -1;
    }
    /// <summary>
    /// Returns the current entity.
    /// </summary>
    object System.Collections.IEnumerator.Current
    {
        get {
            AlignmentEntity entity =
                m_TheEntities.GetEntityByOrder(m_EntityIndex);
            return AlignmentEntityWrapperFactory.WrapEntity(entity);
        }
    }
    /// <summary>
    /// Moves to the next entity.
    /// </summary>
    /// <returns>Returns true if there are entities remaining or
    /// false otherwise.</returns>
    public bool MoveNext()
    {
        m_EntityIndex++;
        return m_EntityIndex < m_TheEntities.Count;
    }
    /// <summary>
    /// Resets the enumerator.
    /// </summary>
    public void Reset()
    {
        m_EntityIndex = -1;
    }
    private AlignmentEntityCollection m_TheEntities;
    private int m_EntityIndex;
}

VB.NET

''' <summary>
''' Enumeration policy that enumerates the alignment entities by
''' sequence in the alignment.
''' </summary>
Public Class BySequenceEnumerationPolicy
    Implements IAlignmentEntityEnumerationPolicy
  ''' <summary>
  ''' Initializes the policy from the alignment entities.
  ''' </summary>
  ''' <param name="entities">Entities to enumerate.</param>
  Public Sub Initialize(entities As AlignmentEntityCollection) _
      Implements IAlignmentEntityEnumerationPolicy.Initialize
    m_TheEntities = entities
  End Sub
  ''' <summary>
  ''' Returns enumerator.
  ''' </summary>
  ''' <returns>Returns enumerator object.</returns>
  Public Function GetEnumerator() As IEnumerator(Of AAlignmentEntity) _
      Implements IAlignmentEntityEnumerationPolicy.GetEnumerator
    Return New BySequenceEnumerator(m_TheEntities)
  End Function
  ''' <summary>
  ''' Returns the enumerator.
  ''' </summary>
  ''' <returns>Returns enumerator object.</returns>
  Private Function System_Collections_IEnumerable_GetEnumerator() _
      As System.Collections.IEnumerator _
      Implements System.Collections.IEnumerable.GetEnumerator
    Return New BySequenceEnumerator(m_TheEntities)
  End Function
  Private m_TheEntities As AlignmentEntityCollection
End Class
''' <summary>
''' Enumerator object that enumerates the entities by sequence order.
''' </summary>
Public Class BySequenceEnumerator
    Implements IEnumerator(Of AAlignmentEntity)
  ''' <summary>
  ''' Initializes the class from the alignment entities.
  ''' </summary>
  ''' <param name="entities">Entities to enumerate</param>
  Friend Sub New(entities As AlignmentEntityCollection)
    m_TheEntities = entities
    m_EntityIndex = -1
  End Sub
  ''' <summary>
  ''' Returns the current entity.
  ''' </summary>
  Public ReadOnly Property Current() As AAlignmentEntity _
      Implements IEnumerator(Of AAlignmentEntity).Current
    Get
      Dim entity As AlignmentEntity = _
        m_TheEntities.GetEntityByOrder(m_EntityIndex)
      Return AlignmentEntityWrapperFactory.WrapEntity(entity)
    End Get
  End Property
  ''' <summary>
  ''' Disposes the object.
  ''' </summary>
  Public Sub Dispose() Implements IDisposable.Dispose
    m_TheEntities = Nothing
    m_EntityIndex = -1
  End Sub
  ''' <summary>
  ''' Returns the current entity.
  ''' </summary>
  Private ReadOnly Property System_Collections_IEnumerator_Current() _
      As Object Implements System.Collections.IEnumerator.Current
    Get
      Dim entity As AlignmentEntity = _
        m_TheEntities.GetEntityByOrder(m_EntityIndex)
      Return AlignmentEntityWrapperFactory.WrapEntity(entity)
    End Get
  End Property
  ''' <summary>
  ''' Moves to the next entity.
  ''' </summary>
  ''' <returns>Returns true if there are entities remaining or
  ''' false otherwise.</returns>
  Public Function MoveNext() As Boolean _
      Implements System.Collections.IEnumerator.MoveNext
    m_EntityIndex += 1
    Return m_EntityIndex < m_TheEntities.Count
  End Function
  ''' <summary>
  ''' Resets the enumerator.
  ''' </summary>
  Public Sub Reset() Implements System.Collections.IEnumerator.Reset
    m_EntityIndex = -1
  End Sub
  Private m_TheEntities As AlignmentEntityCollection
  Private m_EntityIndex As Integer
End Class

The ‘BySequenceEnumerationPolicy’ class uses a ‘BySequenceEnumerator’ that iterates through the entity in sequential order.

Test Commands

The new implementation for the sample commands now can leverage of our new design. The code for the command class will look something like the following.

C#

public class AlignmentEntitiesCommandsColibra
{
    [CommandMethod("CDS_WriteAlignmentEntitiesById")]
    public void CDS_WriteAlignmentEntitiesById()
    {
        doWriteAlignmentEntities(new ByEntityIdEnumerationPolicy());
    }
    [CommandMethod("CDS_WriteAlignmentEntitiesBySequence")]
    public void CDS_WriteAlignmentEntitiesBySequence()
    {
        doWriteAlignmentEntities(new BySequenceEnumerationPolicy());
    }
    private void doWriteAlignmentEntities(
        IAlignmentEntityEnumerationPolicy enumerationPolicy)
    {
        Document current = DocumentManager.ActiveDocument;
        using (Transaction tr = current.StartTransaction())
        {
            // First we select the alignment to write.
            //
            SingleObjectSelector<Alignment> selector =
                new SingleObjectSelector<Alignment>();
            if (!selector.Select(current))
            {
                _output.WriteMessage("\nNo Alignment was selected.");
                return;
            }
            // We create the processor and assign the policy.
            //
            AlignmentEntityProcessor processor =
                new AlignmentEntityProcessor(selector.SelectedId);
            processor.EnumerationPolicy = enumerationPolicy;
                
            // We create the writer and write the information to it.
            //
            DocumentOutputAlignmentEntityInfoWriter writer =
                new DocumentOutputAlignmentEntityInfoWriter(current);
            processor.WriteInfo(writer);
        }
    }
    private Editor _output
    {
        get
        {
            return Autodesk.AutoCAD.ApplicationServices.Application
                .DocumentManager.MdiActiveDocument.Editor;
        }
    }
}

VB.NET

Public Class AlignmentEntitiesCommandsColibra
  <CommandMethod("CDS_WriteAlignmentEntitiesById")> _
  Public Sub CDS_WriteAlignmentEntitiesById()
    doWriteAlignmentEntities(New ByEntityIdEnumerationPolicy())
  End Sub
  <CommandMethod("CDS_WriteAlignmentEntitiesBySequence")> _
  Public Sub CDS_WriteAlignmentEntitiesBySequence()
    doWriteAlignmentEntities(New BySequenceEnumerationPolicy())
  End Sub
  Private Sub doWriteAlignmentEntities(enumerationPolicy _
      As IAlignmentEntityEnumerationPolicy)
    Dim current As Document = DocumentManager.ActiveDocument
    Using tr As Transaction = current.StartTransaction()
      ' First we select the alignment to write.
      '
      Dim selector As New SingleObjectSelector(Of Alignment)()
      If Not selector.[Select](current) Then
        _output.WriteMessage(vbLf & "No Alignment was selected.")
        Return
      End If
      ' We create the processor and assign the policy.
      '
      Dim processor As New AlignmentEntityProcessor( _
        selector.SelectedId)
      processor.EnumerationPolicy = enumerationPolicy
      ' We create the writer and write the information to it.
      '
      Dim writer As New DocumentOutputAlignmentEntityInfoWriter( _
        current)
      processor.WriteInfo(writer)
    End Using
  End Sub
  Private ReadOnly Property _output() As Editor
    Get
      Return Autodesk.AutoCAD.ApplicationServices.Application _
        .DocumentManager.MdiActiveDocument.Editor
    End Get
  End Property
End Class

The Implementation Source Code

The implementation of the commands show some classes the we have not discussed. Even the code in this post refers to some interfaces that we have not covered. The complete implementation can be found in Colibra 1.0.3.0, which you can download and review.

AutoCAD Civil 3D 2012 adds support for some additional entities that were not supported in the 2011 version. For that reason, I updated the drawings to 2012 and ported the Colibra project to use AutoCAD Civil 3D 2012 and Visual Studio 2010. Let me know if you run into any issues.

What’s Wrong With My Alignment Entities? (Part 3)

Note: If you downloaded the source from the previous post, “What’s Wrong With My Alignment Entities? (Part 2)”, you may have a bare implementation of an extension application. This was not intentional; I posted the wrong source file. You can get the right file now.

In my previous post, “What’s Wrong With My Alignment Entities? (Part 2)”, we looked at the ‘AlignmentEntityCollection’ class, and the interfaces it exposes to access alignment entities. We saw how the class provides different ways of accessing the contained entities in the ‘Alignment’ object, and we provided a couple of sample commands to demonstrate the functionality. But when we looked at the output of the commands, there was something that did not make sense. Here is the output from the second command “CDS_DISPLAYALIGNMENTENTITIESBYORDER’.

When we look at the output, we notice a couple of things that do not seem right. First, the entity at sequence 5 has an ‘Entity Class’ type of ‘AlignmentSCS’. This is the same type as the entity at sequence 3, but the entity at 3 has an ‘Entity Type’ of ‘SpiralCurveSpiral’ and contains 3 sub-entities; where, the entity at 5 has an ‘Entity Type’ of ‘SpiralCurve’ and only contains 2 entities.

The underlying object model for alignments reuses some of the entity type classes to hold the information from the different entity types. Therefore to determine the type of entity, we cannot look at the ‘Class Type’ (the value returned by the ‘GetType()’ method in the alignment entity object). Instead, we need to evaluate the ‘EntityType’ property exposed by the object.

The ‘EntityType’ property exposes an enumeration value of type ‘AlignmentEntityType’, and indicates the kind of alignment entity it represents. This property is the only way the kind of entity can be determined. Using the ‘Class Type’ information instead will only lead to errors and subtle “bugs”. The ‘AlignmentEntityType’ enumeration is defined in this way:

public enum AlignmentEntityType
{
  Arc = 0x102,
  CurveCurveReverseCurve = 0x113,
  CurveLineCurve = 0x111,
  CurveReverseCurve = 0x112,
  CurveSpiral = 0x109,
  CurveSpiralSpiral = 0x110,
  Line = 0x101,
  LineSpiral = 0x107,
  MultipleSegments = 0x10b,
  Spiral = 0x103,
  SpiralCurve = 0x108,
  SpiralCurveSpiral = 260,
  SpiralCurveSpiralCurveSpiral = 0x10c,
  SpiralCurveSpiralSpiralCurveSpiral = 0x10d,
  SpiralLine = 0x106,
  SpiralLineSpiral = 0x105,
  SpiralSpiral = 270,
  SpiralSpiralCurve = 0x10f,
  SpiralSpiralCurveSpiralSpiral = 0x10a
}

Unfortunately, a lot of times we need to know the specific ‘Class Type’ when dealing with alignment entities. This is because the interface for specific types differs from one another, and if we need to do something more than what it is exposed in the common interface, we need to cast the object to the correct type. The following table shows the ‘Class Type’ used for each of the ‘Entity Types’ defined in the ‘AlignmentEntityType’ enumeration, as well as the number of sub-entities contained.

 

Entity Type	Class Type	S-E
Line	AlignmentArc	1
Arc	AlignmentCurve	1
Spiral	AlignmentSpiral	1
SpiralCurveSpiral	AlignmentSCS	3
SpiralLineSpiral	AlignmentSTS	3
SpiralLine	AlignmentSTS	2
LineSpiral	AlignmentSTS	2
SpiralCurve	AlignmentSCS	2
CurveSpiral	AlignmentSCS	2
SpiralSpiralCurveSpiralSpiral	AlignmentSSCSS	5
SpiralCurveSpiralCurveSpiral	AlignmentSCSCS	5
SpiralCurveSpiralSpiralCurveSpiral	AlignmentSCSSCS	6
SpiralSpiral	AlignmentSCS (if entity between two lines) or AlignmentSTS (if entity between two curves)	2
SpiralSpiralCurve	AlignmentSSCSS	3
CurveSpiralSpiral	AlignmentSSCSS	3
MultipleSegments	AlignmentMultipleSegments	n/u
CurveLineCurve	AlignmentCTC	3
CurveReverseCurve	AlignmentCRC	2
CurveCurveReverseCurve	AlignmentCCRC	3

There are two things to notice. First, the ‘MultipleSegments’ entity type it is not used at the moment, so you won’t have to deal with it yet. Second, the ‘SpiralSpiral’ type can be contained by one of two classes. If the entity is between two lines, the underlying model will select the ‘AlignmentSCS’ class to hold the entity, but if the entity is located between two curves (arcs), the model will select the ‘AlignmentSTS’ class to represent the entity.

This design may seem confusing, and I can agree it makes the API hard to use, or at least not intuitive. But we have to keep in mind that design decisions are triggered by the requirements of a feature, and I am sure the underlying model was designed in this way for a very good reason.

A different subject is when we need to use the API to implement our applications. Our requirements will be different and maybe this design is not well suited. Fortunately, design patterns provide a good way to encapsulate the underlying implementation and provide an interface that suit our needs. In my next post, I will use established design patterns that will allow me to modify the design design and interface to suit a different set of requirements.

What’s Wrong With My Alignment Entities? (Part 2)

In this second article of the series, we will look at the ‘AlignmentEntityCollection’ class. This class manages the entities in an ‘Alignment’ object, and you can access it through its ‘Entities’ property. The ‘AlignmentEntityCollection’ class exposes an interface, which allows you, among other things, to add, remove, and access the entities of the alignment, but the interface can be tricky sometimes.

We will start by implementing a simple command, ‘CDS_DISPLAYALIGNMENTENTITIES’, that allows users to select an alignment and display the contained entities. We use the prefix ‘CDS’, which stands for “Civilized Development Sample” to insure our command name does not collide with an existing command. The skeleton of the command is very simple. We prompt the user to select an alignment and we display its entities.

[CommandMethod("CDS_DisplayAlignmentEntities")]
public void CDS_DisplayAlignmentEntities()
{
  ObjectId alignmentId = promptForAlignment();
  if (ObjectId.Null != alignmentId)
  {
    displayAlignmentEntities(alignmentId);
  }
}

In the command, we are using two method calls that we have not implemented yet: ‘promptForAlignment()’ and ‘displayAlignmentEntities()’, We will implement them now.

private ObjectId promptForAlignment()
{
  // We use PromptEntityOptions to insure the entity selected
  // is an Alignment object. When filtering for a type of entity,
  // we need to set a reject message in case the user selects
  // an entity type not allowed.
  //
  string promptMsg = "\nSelect Alignment: ";
  string rejectMsg = "\nSelected entity is not an alignment.";
  PromptEntityOptions opts = new PromptEntityOptions(promptMsg);
  opts.SetRejectMessage(rejectMsg);
  opts.AddAllowedClass(typeof(Alignment), false);
  PromptEntityResult result = _editor.GetEntity(opts);
  if (result.Status == PromptStatus.OK)
  {
    return result.ObjectId;
  }
  return ObjectId.Null;
}

The ‘promptForAlignment()’ method allows the user to select an Alignment object that we will use to display the entities. The method uses the ‘Editor’ object of the current document to prompt for the entity. Access to the ‘Editor’ object has been encapsulated in the private property ‘_editor’, which implementation is shown here.

/// <summary>
/// Returns a reference to the Editor of the current document.
/// </summary>
private Editor _editor
{
  get
  {
    if (m_Editor == null)
    {
      m_Editor = 
        Application.DocumentManager.MdiActiveDocument.Editor;
    }
    return m_Editor;
  }
}
 
private Editor m_Editor = null;

We define an ‘Editor’ member variable to hold a reference to the ‘Editor’ object of the current document. We initialize it to ‘null’, and the reference will be acquired the first time the property is invoked. I like to encapsulate this type of object in a property, so I do not have to write the access code all over my program. It gives it a nicer look, and the code is more readable.

Now, it is the time to implement the ‘displayAlignmentEntities()’ method. We start by creating a transaction. I encapsulated the code to create the transaction in the method ‘startTransaction(). With the transaction created, we open the alignment and display its name. Then we loop through the entities and display their id, class type, entity type, and number of subentities.

private Editor m_Editor = null;private void displayAlignmentEntities(ObjectId alignmentId)
{
  using (Transaction tr = startTransaction())
  {
    Alignment alignment = 
      alignmentId.GetObject(OpenMode.ForRead) as Alignment;
    write("\nAlignment Name: " + alignment.Name);
    foreach (AlignmentEntity entity in alignment.Entities)
    {
      write("\n.. Entity ID: " + entity.EntityId);
      write("\n.. Entity Class: " + entity.GetType());
      write("\n.. Entity Type: " + entity.EntityType);
      write("\n.. Subentities: " + entity.SubEntityCount);
    }
  }
}
/// <summary>
/// Starts a new database transaction.
/// </summary>
/// <returns>The new transaction object.</returns>
private Transaction startTransaction()
{
  Database db = HostApplicationServices.WorkingDatabase;
  return db.TransactionManager.StartTransaction();
}

We are ready to run our command. Open in Civil 3D the provided drawing ‘Multiple Alignments.dwg’. In prospector’s center line alignments, you will find an alignment named “SCS+SSC (1)”. Zoom to that alignment and you should see something like the following image.

If you run the command we implemented and select that alignment, you should see the following output in the AutoCAD command line window.

Now, let’s take a look at the alignment geometry in ‘Panorama’. Select the alignment, right-click and select “Edit Alignment Geometry…”. A tool bar will be displayed. The third button from the right “Alignment Grid View” brings the ‘Panorama’ window, which shows the alignment entities.

What’s wrong? From the command output, we see the second entity, which has an ID=2, is shown as an alignment line, but the ‘Panorama’ window shows the second entity as a curve. Furthermore, the ID’s displayed by my command do not seem to match the numbering in ‘Panorama’.

This is due to the fact that the ‘AlignmentEntityCollection’ enumerates the entities ordered by ID. ID’'s are assigned to entities as they are created, and the ID of an entity never changes. When we add an entity an ID is assigned to it. If the entity is then removed, the ID is not reused by the alignment.We cannot assume the alignment entities were created in sequential order from beginning to end; therefore, our command may or may not display the entities sequentially from the beginning of the alignment to its end.

If the sequential order of the entity is important in your program, you cannot enumerate the entities using the default methods. Fortunately, the ‘AlignmentEntityCollection’ provides an interface that allows accessing the entities in sequential order. Let’s create another command (‘CDS_DISPLAYALIGNMENTENTITIESBYORDER’) that allows us to display the entities in sequential order. Most of the code will be the same, so we will refactor our existing code to accommodate the changes and eliminate any duplication.

Looking at our implementation, we see the code that will change is the ‘foreach’ loop that we have in the ‘displayAlignmentEntities()’ method. Let’s extract the code to its own method. This refactoring is called ‘Extract Method’.

private void enumerateEntitiesById(Alignment alignment)
{
  foreach (AlignmentEntity entity in alignment.Entities)
  {
    write("\n.. Entity ID: " + entity.EntityId);
    write("\n.. Entity Class: " + entity.GetType());
    write("\n.. Entity Type: " + entity.EntityType);
    write("\n.. Subentities: " + entity.SubEntityCount);
  }
}

We need a way to modify the method we use to enumerate the entities, so let’s define a delegate type and add a delegate to our class.

// To delegate enumeration of entities.
//
private delegate void EnumerateEntitiesDelegate(Alignment alignment);
private EnumerateEntitiesDelegate EnumerateEntities;

Now, we modify ‘displayAlignmentEntities()’ to call the delegate instead of implementing the ‘foreach’ loop itself.

private void displayAlignmentEntities(ObjectId alignmentId)
{
  using (Transaction tr = startTransaction())
  {
    Alignment alignment = 
      alignmentId.GetObject(OpenMode.ForRead) as Alignment;
    write("\nAlignment Name: " + alignment.Name);
    EnumerateEntities(alignment);
  }
}

We need to implement our new command and modify the existing one to assign the correct method to delegate. Since most of the code is the same for both commands, let’s use ‘Extract Method’ again to refactor and eliminate duplication.

[CommandMethod("CDS_DisplayAlignmentEntities")]
public void CDS_DisplayAlignmentEntities()
{
  EnumerateEntities += enumerateEntitiesById;
  doDisplayAlignmentEntities();
}
[CommandMethod("CDS_DisplayAlignmentEntitiesByOrder")]
public void CDS_DisplayAlignmentEntitiesByOrder()
{
  EnumerateEntities += enumerateEntitiesByOrder;
  doDisplayAlignmentEntities();
}
private void doDisplayAlignmentEntities()
{
  ObjectId alignmentId = promptForAlignment();
  if (ObjectId.Null != alignmentId)
  {
    displayAlignmentEntities(alignmentId);
  }
}

All we need to do now, it is implement the ‘enumerateEntitiesByOrder()’ method that we are assigning to the delegate in our latest command.

private void enumerateEntitiesByOrder(Alignment alignment)
{
  AlignmentEntityCollection entities = alignment.Entities;
  for (int i = 0; i < entities.Count; i++)
  {
    AlignmentEntity entity = entities.GetEntityByOrder(i);
    write("\n.. Entity Sequence: " + i);
    write("\n.. Entity Class: " + entity.GetType());
    write("\n.. Entity Type: " + entity.EntityType);
    write("\n.. Subentities: " + entity.SubEntityCount);
  }
}

We can run the new command using the previous drawing and alignment, and you should see the following output.

As you can see, the entities are now enumerated in the order they appear at the ‘Panorama’ window. Our second entity is an ‘Arc’ indicated as ‘Curve’ in ‘Panorama’, and our sequence goes from 0 to 6 because the ‘AlignmentEntityCollection’ is a zero-based collection. You can show the same sequence number by adding 1 to the index.

There are still some confusing aspects to the output. If you look at the entity at sequence 5, you will see its class type is ‘AlignmentSCS’, which seems to indicate it is a ‘Spiral-Curve-Spiral’ and should contain three sub-entities. But if we look at the entity type, we see it is a ‘Spiral-Curve’, and it only contains two sub-entities. In my next post, I will talk about this discrepancy and how it should be handled in your code. For now, you should download and review the complete sample and test drawing.

P.S. You may be wondering what the ‘write()’ method does. Here is the implementation, which is also provided with the full source.

/// <summary>
/// Writes a message string to the AutocAD command line window.
/// </summary>
/// <param name="msg">String to write.</param>
private void write(string msg)
{
  _editor.WriteMessage("\n" + msg);
}

P.P.S. There is some duplication that it is still bothering me. Most of the implementation of ‘enumerateEntitiesById()’ and ‘enumerateEntitiesByOrder()’ is the same. I will leave it as an exercise for you to refactor the code and elimintate the duplication.

P.P.P.S In case you were wondering what pattern we used when we introduced the delegate to enumerate the entities, it is the ‘Strategy Pattern’, which allows to change the behavior of a class by changing the algorithm it uses. Delegates in .NET are an easy way to implement the ‘Strategy Pattern’.

P.P.P.P.S. Apparently, I posted the wrong source file. The link should take you to the correct .zip file now.

What’s Wrong With My Alignment Entities? (Part 1)

Initially, I was planning a quick post to demonstrate the use of the Alignments API; concretely, the access to alignment entities and their types. As I was writing the code and evaluating the use of the API, it became obvious there are a couple of areas in desperate need of an explanation, and trying to do so in a single post, will make the article long and tedious.

What I will do instead is a series of postings, each one of them, explaining a specific “gray” area, and at the end, I will provide some extensions to ‘Colibra’ that, hopefully, will make working with alignment entities easier.

The first post will cover the ‘AlignmentEntityCollection’ class, which provides access to the entities in an alignment. The ‘AlignmentEntityCollection’ object is provided by the ‘Entities’ property of the ‘Alignment’, and defines an interface to access individual ‘AlignmentEntities’ by order and ID.

In a subsequent post, I will provide information about alignment entity types and the difference between ‘AlignmentEntity.GetType()’ and ‘AlignmentEntity.EntityType’. This is crucial to understand how to work with alignment entities.

Finally, I will provide some ‘wrapper’ classes in the ‘Colibra’ library to simplify working with alignment entities. I do not expect to provide a complete wrapper of the Alignments API, but I will provide a good starting point for you to leverage depending on your needs.

The alignment object and its entities are a very important piece of the Civil 3D API. Understanding how it works, it is crucial to understand other objects in the API. In this series, I will reveal the secrets of the alignment entities API, and how to work efficiently with them.

New Surfaces .NET API Web Cast

It has been a few hectic weeks around here. With the release of AutoCAD Civil 3D 2012, we need to plan for our next release. And that is what I have been doing lately. This has prevented me from posting to the blog more often, but now that we are getting a handle on what the next versions of the API are going to look like, I am ready to post again. I have a set of articles, which I am sure they will be of high interest, and you will not want to miss. And I will start with this one.

Some of you may already know Augusto Goncalves and Partha Sarkar. They are developers working with ADN and you might have seek their help in the past with some API issue. They have prepared a Web Cast about the new Surfaces .NET API and made it available to the public. You can view it on-line, or you can download it and watch it locally.

Thanks to both of them for doing this, and I am sure in the near future we will start seeing more content that they will provide in this blog.

AutoCAD Civil 3D 2012 Released

Today is the day. AutoCAD Civil 3D 2012 is out the door, and with it, the
many features you have been hearing about. This has been a very exciting year
where all the feature teams have worked very hard to deliver the most stable
release full of features requested by our customers.

I already talked about what is new in the API, but what I have not told you yet is
that the full documentation for the API, as well as the product, is available
online. You can now access all the information available about AutoCAD Civil 3D
2012 development at the Autodesk WikiHelp website. Make sure you create an Autodesk
SSO (Single Sign-On) account if you have not already do so, to be able to
participate in the content.

I want to congratulate the team on our “best release yet!”.

Developing Applications for AutoCAD Civil 3D 2012

Visual Studio 2010 was released by Microsoft about a year ago. Since then, some of you have selected this IDE as your default development environment. I, personally, like Visual Studio 2010 a lot, and I am hoping to switch completely very soon. But there are a couple of issues you need to be aware if you plan to use the latest version of Microsoft’s phenomenal development environment.

Writing C++ Code

If your application is written in C++, the default Visual C++ 2010 compiler is not compatible with the API’s provided by Civil 3D 2012. This means that if you are using ‘Real DWG’, ‘Object ARX’, the ‘Custom Draw’ API, or using COM from C++, you will have to compile and link your programs using the Visual C++ 2008 compiler. You can still use Visual Studio 2010 as your development environment, but you will have to modify your project settings, so the Visual C++ 2008 compiler is used. You do this in your project properties by going to ‘Configuration Properties > General’ and setting the ‘Platform Toolset’ property to ‘v90’. Notice that Visual Studio 2010 does not install the ‘v90’ version of the toolset, so you still need Visual Studio 2008 installed on your machine.

Writing Managed/.NET Code

In the world of .NET and managed code, things are not so straight forward. When writing managed code, you can choose either version of Visual Studio, 2008 or 2010, but you also need to choose your target platform, .NET 4.0 or an earlier version.

If you plan to use Visual Studio 2008, the choice is easy because .NET 4.0 is not supported by this environment. Your applications will target earlier versions of the framework, which is totally fine, but there is a small caveat.

AutoCAD 2012 and all vertical applications, including Civil 3D 2012, install .NET Framework 4.0 during the installation process. At the same time, they configure acad.exe to use .NET 4.0 as the default run-time version of the framework. DLLs targeting earlier version can still be loaded, and they work just fine. But when you are developing your own applications, you need to debug your code, and there is a little problem. By default, Visual Studio 2008 will see that acad.exe is loading a newer version of the .NET Framework that does not know how to handle. The culprit is ‘acad.exe.config’, which contains the following line.

<supportedRuntime version="v4.0"/>

This entry in ‘acad.exe.config’ dictates .NET 4.0 should be loaded, and Visual Studio 2008 does not know how to handle that version. If you use Visual Studio 2008 as your IDE, you need to edit that line to enable debugging of your application. The change I simple; you just need to modify the version number.

<supportedRuntime version="v2.0.50727" />

Notice this change also applies if you are using Visual Studio 2010, but you target earlier versions of the framework in your projects.

The Civil 3D API team has been using both Visual Studio versions for many months now, and we have not found any issues with either one of them, nor targeting the different versions of the framework. However, there has been some reports by some Beta customers where they have run into debugging problems when using Visual Studio 2010 and targeting .NET framework 4.0. Kean Walmsley wrote an article in his blog, “Through the Interface” in April of 2010 about this issue. His article, “Hitting Breakpoints in .NET Class Libraries…” gives an explanation of the problem and different ways to work around it.

I have not run into this issue myself, but I have seen customers reproduce the problem. One of them even went through the trouble of creating a VM to reproduce it, and sent the VM to me. Switching the target platform to .NET Framework 3.5 and editing the ‘acad.exe.config’ file in the way I explained seemed to take care of the problem. There were, however, some suspicious characteristics about this VM.

First, there was no version of Visual Studio 2008 installed in the machine. I do not know if this makes any difference, but it certainly is something to look at. I have both versions of Visual Studio installed in all my computers, and I have never run into issues.

Also, the class library project was referencing some system assemblies that were never used. I do not know if their real project uses these system assemblies, but in the trim-down version they sent me they were never used. In my quick test, System.Data.dll was looking suspicious because it was not used, but the wrong version of the DLL was being loaded into memory when Civil 3D was started with the .NET 4.0 framework set as a target.

Again, if you run into problems, make sure to review Kean’s article, and the links it contains. There is a lot of information in them that might help you solve the problem. And do not hesitate to drop me a line or post a comment if you have more information, or you are not able to solve the issue. This problem really concerns us, and we need as much information as we can get.

What’s New with the AutoCAD Civil 3D 2012 API

The 2012 releases will soon be out the door, and with them, all the excitement of the new features. We, the API team, have also very exciting news for you. We worked very hard for the past year to deliver new features and enhancements to you. Keep reading if you are curious about what’s new with the AutoCAD Civil 3D API.

The major API feature included in the 2012 release is the Surfaces .NET API. This feature was very limited in the COM API, and some will say very hard to use. The Surfaces COM API exposed the feature functionality at a very low-level, making it very hard to use even for experienced users. Using it gives me the creeps, and I find it very hard to do anything useful with it. The good news is, it is all in the past.

With the Surfaces .NET API, we took a step back and looked at the feature functionality to determine what users will want to do with the API. We redesign the interface to provide real abstractions that are easy to use and give you all the power. Long gone are the arrays of doubles required to interact with points and triangles. Now, there are surface vertices and surface triangle objects that provide the necessary interfaces to get the job done. We also looked at features customers were requesting and implemented them in the new .NET API. It took us quite some time to get it done, but I am sure you and all our customers will be very happy with the new implementation.

Back in the 2011 release time-frame, we had several customers reporting huge performance degradation when using the Corridors API. We have always told customers to move from COM to .NET as new APIs become available, but doing so with the Corridor API was near impossible because of the performance issues. We worked hard profiling Corridors, and sure enough, the API was consuming most of the resources available in high-end machines. Once we found the bottlenecks, we started refactoring the code to improve it and make memory management better. The results are outstanding, and you will notice them on your first run. These improvements were made available with the AutoCAD Civil 3D 2011 SP1 release, but 2012 includes other fixes and improvements. As an example, we added support for ‘SetAxisOfRotationCrownPoint’, ‘SetAxisOfRotationInformation’, and ‘SetAxisOfRotationSERange’ to the ‘CorridorState’ object.

You will also find other minor, although important, improvements in the new 2012 API. You will find support for new alignment entities that were added to the feature. We added new overloaded methods to the ‘AlignmentEntityCollection’ class to have more control adding curves and spirals, and expose the label type for the alignment indexed PI label style.

Finally, we completed support for existing features where we might have missed some functionality or new functionality was added. We improved the QTO API to add support for sectional, volume and quantity takeoff results, and added support for the new rotate label feature in 2012. And, we completed the Styles and Settings API, so you can access all styles and settings exposed by Civil 3D 2012.

This was a great release, and I want to congratulate my team for their effort to make it possible. There was a lot of work to be done, but they pull it out, most important, they maintained stability and quality. With the new features and improvements, I am sure our customers will be very happy to upgrade.