EC Data

This articles discusses Python classes for handling EC Data programmatically. By EC Data we mean information about a DGN file, model or element. That information is stored in a DGN file. The data are linked to an object via its unique Element ID. An Element ID is a 64-bit integer that is unique in the context of a DGN file.

EC Data

MicroStation stores EC data about a DGN file, a DGN model or DGN elements. Some data are added automatically by MicroStation. For example, the Total Editing Time is a statistic stored about each DGN file. As a user edits a file, MicroStation updates the Total Editing Time value.

Other data may be added by an application or a user: a user might want to use Item Types to annotate DGN elements in a DGN file. Item Types use a simple, user-defined, EC Schema.

EC Instance

An EC Instance is an object that stores EC instance data about a DGN file, DGN model or DGN Element. You interrogate a DGN object to find a list of ECInstances linked to that object.

EC Schema

An EC Schema is the in-memory representation of a schema as defined by ECSchemaXML. Many schemas are delivered with MicroStation. You'll find them in the ECSchemas sub-directory of MicroStation's installation. On my computer, that's

C:\Program Files\Bentley\MicroStation 2025\MicroStation\ECSchemas

Each schema is an XML file, so you can read it with a plain text editor or, preferably, an XML editing app. There are some mentioned here.

Read but don't edit!

EC Schema, Class and Property

EC Schema

An EC Schema defines one or more EC classes. For example, schema DgnFileSchema defines class DgnFileProperties.

EC Property

An EC class defines a number of EC Properties. For example, DgnFileProperties defines property TotalEditingTime.

I've complied a list of EC classes.

EC Value

An EC Value stores EC data in memory before it is written to a DGN file. ECValue is a variant type: it can store various types of data including arrays of other ECValues.

An ECValue can be tricky to use in Python. Python wraps the C++ ECValue class, but there are idioms in C++ that don't translate well to Python. Read more about the ECValue class in Python.

EC Property

An EC Property describes the data that can be attached to a DGN object as EC Instance data. Data may be numeric, text, or an array.

EC Query

To interrogate a DGN file programmatically to find instance data, use an ECQuery. An ECQuery lets you instruct your code where to look (i.e. DGN file, DGN model or DGN element) and what to look for (i.e.  EC Schema and EC Class).

Help for the MicroStationAPI tells us …

An ECQuery is somewhat analogous to a SQL query and is used with DgnECManager.FindElementInstances to find ECInstances that satisfy the query's 'where' clause.

Use AddSearchClass to specify what ECClasses of ECInstances you wish to find. Use SetSelectProperties to indicate whether returned ECInstances should include their values (or just InstanceId) Use SetWhereCriterion to specify a 'where clause' Use SetPropertyValuePreFilter to filter ECInstances based on testing all of their property values, e.g. similar to a full text search.

Dgn EC Manager

The Dgn EC Manager.

Help for the MicroStationAPI tells us …

DgnECManager handles persistence of ECInstances including CRUD operations for ECN.Instances and EC.RelationshipInstances and "FindElementInstances" operations.

It also handles ECSchema discovery and locating.

DgnECManager.GetManager() is a class method. It lets you obtain an EC Manager object, which you use subsequently to manufacture other EC class instances. For example …

from MSPyECObjects import *
mgr = DgnECManager.GetManager()

EC Examples

Several examples of EC programming are installed with MicroStation Python. This page tells you how to find them on your computer.

Questions

Post questions about MicroStation Python programming to the MicroStation Programming Forum.