MicroStation Engineering Content: Schemas

Bentley Systems introduced Engineering Content with MicroStation CONNECT in 2015. Engineering Content is commonly abbreviated to EC.

The foundation of Engineering Content is contained in its schemas. A schema is a general framework or category that organizes and interprets information.

MicroStation Schemas: Folders and Files

MicroStation's EC schemas are defined in XML files that are installed in the ..\MicroStation\ECSchemas folder (something like C:\Program Files\Bentley\MicroStation 2026\MicroStation\ECSchemas).

Under that ..\MicroStation\ECSchemas folder you'll see sub-folders including ..\MicroStation\ECSchemas\Dgn. There is a number of XML files in that folder. Most you will seldom use, but one or two are invaluable as you venture along the path to EC enlightenment …

• BaseElementSchema.01.00.ecschema.xml
• DgnElementSchema.01.00.ecschema.xml
• DgnModelSchema.01.00.ecschema.xml
• DgnFileSchema.01.00.ecschema.xml
• MstnPropertyFormatter.01.00.ecschema.xml

Never edit, modify or delete those files! You can inspect them, and since they are XML it's best to use an XML reader such as NotePad++ or XMLSpy. Prefer to open schema files read-only.

The files are large. The first we'll look at is BaseElementSchema.01.00.ecschema.xml, which contains about 13,000 lines. They are designed to be read by an app that understands their structure and content. That app is MicroStation!

For example, here's the beginning of ECClass Segment. A segment is part of a line or line-string …

<ECClass typeName="Segment" isStruct="True" isDomainClass="True">
     …
    lines omitted
     …
</ECClass>

That XML structure is intended to build an MSPyECObjects.ECClass at run-time.

BaseElementSchema

BaseElementSchema.01.00.ecschema.xml is intended to be merged (overridden) by other schemas. For example, the DgnElementSchema (DgnElementSchema.01.00.ecschema.xml) references the base schema in this line near the beginning of the file …

<ECSchema schemaName="DgnElementSchema" nameSpacePrefix="dgnElem" version="1.0" displayLabel="Dgn Elements" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.2.0">
    <ECSchemaReference name="BaseElementSchema" version="01.00" prefix="baseElem" />
     …
    lines omitted
     …
</ECSchema>

DgnElementSchema

The DgnElementSchema (DgnElementSchema.01.00.ecschema.xml) is the schema used for common DGN elements. You will recognise such names as TextElement, ConeElement, LineElement and many more. Here is the ECClass meta-data for a LineElement …

<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>

The first few lines tell us that a LineElement …

• is a graphical element (it inherits from BaseClass GraphicalElement
• inherits from baseElem:MstnLineSegments

Use the element information tool (Ctrl-I) on a line element in MicroStation, and you can see how those class definitions contribute to the display.

EC Classes at Runtime

As MicroStation starts, it reads those schema files and builds an EC model in memory. That EC model is stored in MicroStation's non-graphical cache — as a user, you can't see it.

Each DGN element has a link to its EC class. The class determines how that element is presented to you. The EC class participates in MicroStation's rendering of the element. It also participates in tools such as Element Properties that display element data in tabular form. The EC class determines the labels and data that are shown.

MstnPropertyFormatter

As a programmer, you know that DGN elements are stored in a DGN model, and that a DGN model has a Units property. Units specifies the master units, sub-units and working units used in that DGN model. Different models may have different Units.

Master Units are typically a human-scale dimension, such as metres or feet.

DGN elements are created and drawn in the context of their DGN model. The units used are always the DGN model's unit of resolution (UORs). UORs may be several orders of magnitude different to master units.

Line Measurement

When presenting DGN element data to a user, we need to convert from UORs to master units. It's common to see legacy code like this when presenting the length of a line …

model_info = dgnModel.GetModelInfo()
scale_factor = model_info.UorPerMeter
line_length = curve.Length()/scale_factor
print(f"line {line_length}m")

scale_factor is the conversion from UORs to metres in the DGN model. The line length, measured in UORs, is divided by the scale_factor for human consumption.

Using the ECClasses and ECProperties provided by the MstnPropertyFormatter you can move to a better way of formatting DGN measurements. For example, the label below, created by LA Solutions' AreaAnnotator, shows an element's area formatted in both square metres and square feet …

Formatting Classes

Each DGN element type has a corresponding formatter in MstnPropertyFormatter. Rather than the above hand-crafted formatting, we create a formatting class in our code that uses the ECClasses and ECProperties. We no longer have to write an arithmetic conversion. Now we can instantiate a formatter class, set its properties to suit our display requirements, and tell it the DGN element to work with. Then, use the result in the user interface.

Use a formatter to produce the result of a measurement, then create a TextField to display those data. The TextField knows that it's connected to an element, and if you modify that element then the TextField updates automatically to show the new data.

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.