MicroStationAPI: Query EC Instances

MicroStationAPI

Introduction

The MicroStation Development Library (MDL) and MicroStationAPI provide APIs for developers wanting to create custom applications for MicroStation^® from Bentley Systems. We create a MicroStation application as a DLL, written using C++ and built with the Microsoft C++ compiler and linker provided with Visual Studio.

When editing your source code, you can choose whether to use Microsoft Visual Studio, Microsoft Visual Studio Code, or one of your favourite text editors.

When building your app, you can use Visual Studio or the Bentley Systems make (bmake) tools.

ECQuery

MicroStation EC data, sometimes in the form of Item Type data, is attached to a DGN element, DGN model or DGN file. Often we want to query a DGN model to get information about those DGN elements tagged with our Item Type data.

EC Header files

There's a bewildering list of header files that you will need when writing an application for Item Types. I created a get-all header so I don't have to remember …

#include <DgnPlatform/CustomItemType.h>
#include <DgnPlatform/DgnECFinders.h>
#include <DgnPlatform/DgnECInstance.h>
#include <DgnPlatform/DgnECManager.h>
#include <DgnPlatform/ECReportNode.h>
#include <DgnPlatform/DgnFile.h>
#include <DgnPlatform/ECQuery.h>
#include <DgnPlatform/WhereCriterion.h>
#include <DgnPlatform/XDataTreeOwner.h>
#include <ECObjects/ECObjectsAPI.h>
#include <ECObjects/ECSchema.h>
#include <ECObjects/ECValue.h>

EC Scope

You need a scope that tells the EC manager where to look …

FindInstancesScopeOption option (DgnECHostType::Element);
FindInstancesScopePtr scope = FindInstancesScope::CreateScope (*ISessionMgr::GetActiveDgnModelP (), option);

EC Query

And you need a query. This query finds all instances of a named Item Type schema and class name …

const bool& Polymorphic { true };
// See below for more information about internal names
ECQueryPtr query = ECQuery::CreateQuery (internalSchemaName, internalClassName, Polymorphic) ;

Queries may be more selective, supposedly more like an SQL query. However, there is no query language similar to SQL or XQuery: a query must be constructed programmatically. There are few published rules and fewer examples.

EC Instance List

Put them together …

DgnECManagerR    manager   { Bentley::DgnPlatform::DgnECManager::GetManager () };
DgnECInstanceIterable instances { manager.FindInstances (*scope, *query, nullptr) };

Create an Element Agenda

Convert EC Instances to an Element Agenda …

size_t 	EnumerateInstances (ElementAgendaR  elements,
                            Bentley::DgnPlatform::
                            DgnECInstanceIterable& instances)
{
  size_t count { 0 };
  for (DgnECInstanceIterable::const_iterator it = instances.begin(); it != instances.end(); ++it)
  {
    DgnECInstancePtr instance = *it;
    DgnElementECInstanceCP elemInstance = instance->GetAsElementInstance();
    if (elemInstance)
    {
      ++count;
      ElementHandleCR eh = elemInstance->GetElementHandle();
      const bool&  DuplicateDescriptor = true;
      EditElementHandle eeh(eh, DuplicateDescriptor);
      elements.Insert (eeh);
    }
  }
  return elements.size ();
}

EC Internal Names

Internal names are used by the EC API. User-supplied names for schemas and classes often contain undesirable characters such as spaces. There are name-mangling functions that convert a user name to an internal name. For example …

ItemTypeLibraryPtr lib = ItemTypeLibrary::FindByName (L"Your Item Type Library Name", *MicroStation::GetActiveDgnFile ());
return lib->GetInternalName ();

However, not all classes have a GetInternalName() member. Here's an overloaded method that works with all classes.

Header …

Bentley::WString GetInternalName (WStringCR            ecName);
Bentley::WString GetInternalName (ItemTypeCR           itemType);
Bentley::WString GetInternalName (ItemTypeCP           itemType);
Bentley::WString GetInternalName (CustomPropertyTypeCR customType);
Bentley::WString GetInternalName (CustomPropertyCR     itemType);

Implementation …

Bentley::WString GetInternalName (WStringCR	name)
{
  WString	internalName;
  ECNameValidation::EncodeToValidName (internalName, name);
  return 	internalName;
}

Bentley::WString GetInternalName (ItemTypeCR	itemType)
{
  return GetInternalName (itemType.GetName ());
}

Bentley::WString GetInternalName (ItemTypeCP	itemType)
{
  return GetInternalName (itemType->GetName ());
}

Acknowledgements

This article distils tips that Bentley Systems staffer Paul Connelly and others have given over the years.

Questions

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