MicroStationAPI CONNECT: EC Element Properties

Introduction

A MicroStation DGN file is a container: it contains one or more DGN models. A DGN model is also a container: it contains DGN elements, reference attachments and other objects. This article discusses EC schemas, stored in a DGN file, and EC instances, stored in a DGN model. An EC instance is a set of data attached to a DGN element that conforms to an EC schema.

XML files delivered with MicroStation define multiple EC schemas. They define DGN element, model, file and other classes and properties.

EC instance data is visible in MicroStation. Pick an element, and use key chord Ctrl-I to pop the Properties dialog …

You can see geometric properties Segments, Count and Total Length. Each Segment (displayed as Segments[n]) has its own set of properties. This series of articles shows how to obtain an EC instance from a DGN element, then get EC classes and properties from that instance.

Schema Files

Schema XML files are installed with MicroStation. You'll find them in folder ..\MicroStation\ECSchemas and its sub-folders. There are a lot of schemas: some more obscure than others. Those that concert DGN elements, for example, include …

Base Element Schema (BaseElementSchema.01.00.ecschema.xml)
DGN Element Schema (DgnElementSchema.01.00.ecschema.xml)

You will find many more schema files in the ..\MicroStation\ECSchemas folder.

EC Class Inheritance

A schema defines one or more EC classes. Each class has one or more properties. A schema may inherit from another class or several classes. For example, the LineElement class, found in the DGN Element Schema, inherits from two classes, which are …

MstnLineSegments, found in the Base Element Schema
GraphicalElement, found in the DGN Element Schema

EC Line Element

In this article, we'll focus on the EC LineElement. It is one of the simpler EC classes …

<ECClass typeName="LineElement" isDomainClass="True" displayLabel="Lines">
    <BaseClass>GraphicalElement</BaseClass>
    <BaseClass>baseElem:MstnLineSegments</BaseClass>
    <ECCustomAttributes>
      <DisplayOptions xmlns="Bentley_Standard_CustomAttributes.01.10">
        <Hidden>False</Hidden>
      </DisplayOptions>
      <ElementHeaderPropertyOverrides>
        <PropertyNames>
          <string>Thickness</string>
          <string>LineStyleParams</string>
        </PropertyNames>
      </ElementHeaderPropertyOverrides>
     <CustomImageSpecification xmlns="Bentley_Standard_CustomAttributes.01.10">
      <Moniker_Default>ECLiteralImage://Line</Moniker_Default>
      <Moniker_Expanded>ECLiteralImage://Line</Moniker_Expanded>
      <Moniker_Collapsed>ECLiteralImage://Line</Moniker_Collapsed>
     </CustomImageSpecification>
    </ECCustomAttributes>
    <ECArrayProperty propertyName="Segments" typeName="baseElem:Segment" minOccurs="1" maxOccurs="1" isStruct="True" displayLabel="Segments">
      <ECCustomAttributes>
        <Category xmlns="EditorCustomAttributes.01.00">
          <Standard>8</Standard>
        </Category>
        <PropertyPriority xmlns="EditorCustomAttributes.01.00">
          <Priority>350000</Priority>
        </PropertyPriority>
        <MembersIndependent xmlns="EditorCustomAttributes.01.00" />
        <ExtendType xmlns="EditorCustomAttributes.01.00">
          <Standard>12</Standard>
        </ExtendType>
        <ArrayBehaviorAttributes xmlns="EditorCustomAttributes.01.01">
          <SupportsAddAndRemove>False</SupportsAddAndRemove>
        </ArrayBehaviorAttributes>
      </ECCustomAttributes>
    </ECArrayProperty>
  </ECClass>

I have no idea of the purpose of all of those properties, so I'll focus on those that are useful in the project I'll describe. If we want to extract information about an EC LineElement, then the interesting properties are Segments and TotalLength.

TotalLength has a double value and its purpose is self-evident. Segments is an ECArrayProperty property of the inherited class MstnLineSegments (see Base Element Schema). It defines a list of Segment (see Base Element Schema), which has these useful properties …

Segment Class Properties
Property	Type	Display Label
Start	point3d	Start
End	point3d	End
Length	double	Length
Direction	double	Direction
ElevationAngle	double	Elevation Angle
DeltaX	double	Delta X
DeltaY	double	Delta Y
DeltaZ	double	Delta Z
Delta	point3d	XX-Delta-XX

For a LineElement, the array of Segments will have exactly one entry: a Segment. A LineStringElement or ShapeElement will have an indefinite number of Segments.

View EC Classes

The Bentley Systems Class Editor is delivered with product PlantDesign Manager. Be aware that it's not an editor, but a file viewer. As valid XML files, you can view any EC Schema using something like NotePad++ or XML Spy.

	NotePad++
	XML Spy

Navigate EC Classes

We want to be able to navigate an EC class and its sub-classes and properties. For example, we want to extract the property values — such as Length and Direction — of a LineElement. Each DGN element in a DGN model holds an instance (ECInstance) of its EC class. From that instance we can obtain the corresponding ECClass and its contents. However, navigation is not simple. It's obscured by an API that does not seem a good fit with the straightforward EC class structure.

API Classes

The API does not have, for example, an ECLineElement class. Rather, it has a number of classes that we use to parse EC data in order to build a data structure. C++ EC classes include the following (the .NET API is similar) …

C++ EC Classes
Class Name	Comment
`ECClass`	The in-memory representation of an EC class
`ECInstance`	An instance of an EC class attached to a DGN element
`ECProperty`	A named property that contain a value
`ECQuery`	An ECQuery is somewhat analogous to a SQL query and is used with `DgnECManager::FindElementInstances`
`ECValue`	A variant
`StructECProperty`	The in-memory representation of an `ECProperty` as defined by ECSchemaXML
`ArrayECProperty`	The in-memory representation of an `ECProperty` as defined by ECSchemaXML

This web page is full, so move onto Parsing an EC instance.

MicroStation and Application Development

MicroStation^® is a computer-aided-design (CAD) tool produced by Bentley Systems. It is used by engineers, architects, and draughting technicians to create 3D models and 2D drawings.

MicroStation can be customised. Bentley Systems themselves have many applications for specialised markets that use MicroStation as a platform. Third-parties likewise may use MicroStation as a platform on which to develop their application software. Bentley Systems provide the MicroStation Software Development Kit (SDK) that software developers use to create their applications.

The CONNECT SDK has several libraries …

the MicroStationAPI is a C++ library
the DgnPlatformNet, MstnPlatformNet and some others are .NET libraries

This article concerns the MicroStationAPI. The MicroStationAPI contains thousands of functions that provide a C++ interface.

Questions

Post questions about C# and C++ to the MicroStation Programming Forum.