The EPLAN API allows accessing object properties, i.e. characteristics that are visible in GUI in the Properties dialog. 

This is possible through the  Properties  property which is defined for almost all data model objects. 

The list of all available properties for a particular object can be found in the properties of the  Properties  class (for example  Properties::AllMDSymbolLibraryPropIDs). 

Property types

EPLAN properties are typed. The property values can have one of the following types: 

• bool
• int
• double
• DateTime
• PointD
• MultiLangString

With help of the PropertyDefinition.PropertyType, you can determine the type of a property:

The following example gets the type of a page property: 

PropertyDefinition.PropertyType oPropType = oPage.Properties[Properties.Page.DESIGNATION_PLANT].Definition.Type;

Dim oPropType As PropertyDefinition.PropertyType = oPage.Properties(Properties.Page.DESIGNATION_PLANT).Definition.Type

Setting and getting a property

The following example shows how to set a  bool  property: 

oFunction.Properties[Properties.Function.FUNC_ARTICLE_SUPPRESSINPARTSLIST] = true;

oFunction.Properties(Properties.Function.FUNC_ARTICLE_SUPPRESSINPARTSLIST) = PropertyValue.op_Implicit(True)

The following example shows how to get a  MultiLangString  property (project description): 

MultiLangString mlTest = oProject.Properties[Properties.Project.PROJ_INSTALLATIONNAME];

Dim mlTest As MultiLangString = oProject.Properties(Properties.Project.PROJ_INSTALLATIONNAME).ToMultiLangString()

As an alternative syntax, you can also write: 

MultiLangString mlTest = oProject.Properties.PROJ_INSTALLATIONNAME;

Dim mlTest As MultiLangString = oProject.Properties.PROJ_INSTALLATIONNAME.ToMultiLangString()

Finally an example that loops over all  string  properties of a project: 

 string strTmp = string.Empty;
 PropertyValue oPropValue;
 // Iterate over all project properties
 foreach (AnyPropertyId hPProp in Eplan.EplApi.DataModel.Properties.AllProjectPropIDs)
 {
     // Check if exists
     if (!m_oProject.Properties[hPProp].IsEmpty)
     {
         if (m_oProject.Properties[hPProp].Definition.Type == PropertyDefinition.PropertyType.String)
         {
             // Read string property
             oPropValue = m_oProject.Properties[hPProp];
             strTmp = oPropValue.ToString();
         }
     }
 }

Dim strTmp As String = String.Empty
Dim oPropValue As PropertyValue
' Iterate over all project properties
Dim hPProp As AnyPropertyId
For Each hPProp In  Eplan.EplApi.DataModel.Properties.AllProjectPropIDs
   ' Check if exists
   If Not m_oProject.Properties(hPProp).IsEmpty Then
      If m_oProject.Properties(hPProp).Definition.Type = PropertyDefinition.PropertyType.String Then
         ' Read string property
         oPropValue = m_oProject.Properties(hPProp)
         strTmp = oPropValue.ToString()
      End If
   End If
Next hPProp

Setting name properties

var functionBasePropertyList = new FunctionBasePropertyList();
// Set function name
functionBasePropertyList.DESIGNATION_LOCATION = "A1";
functionBasePropertyList.DESIGNATION_PLANT = "E01";
oNewFunction.NameParts = functionBasePropertyList;

Conversion property value to another types

It is possible to get a property as a value of the .NET Framework type or EPLAN API type (for example  Eplan.EplApi.Base.MultiLangString). It can be done explicitly by the  PropertyValue.To<type>(), for example:

string strStringValue = oFunction.Properties.FUNC_CODE.ToString();  

or implicitly:

int nValue = oFunction.Properties.FUNC_CRAFT;

It is not allowed to convert the property value to a non-matching type, for example  MultiLangString  to  int. In such cases, a runtime warning is generated (as an EPLAN system message) or an exception is thrown:

string strValue = oArticle.Properties.ARTICLE_DEPTH.ToString(); // Will generate a system warning
double dValue = oArticle.Properties.ARTICLE_DEPTH.ToDouble(); // OK
string strValue2 = oArticle.Properties.ARTICLE_DEPTH.ToDouble().ToString("0.00", CultureInfo.InvariantCulture); // Also OK

Here is a table that shows which conversions are allowed:

Indexed properties

Properties can have more than one value. In this case, we call it an "indexed property". The index is passed after the property designation. The example gets the index 1 of the function property  FUNC_CONNECTIONDESIGNATION: 

strConnDes1 = oFunction.Properties[Properties.Function.FUNC_CONNECTIONDESIGNATION, 1].ToString();

strConnDes1 = oFunction.Properties(Properties.Function.FUNC_CONNECTIONDESIGNATION, 1).ToString()

Alternatively: 

strConnDes1 = oFunction.Properties.FUNC_CONNECTIONDESIGNATION[1].ToString();

strConnDes1 = oFunction.FUNC_CONNECTIONDESIGNATION(1).ToString()

User-defined properties

EPLAN API supports also user-defined properties that were introduced in EPLAN 2.4.

The following enhancements were added due to it: 

• Access to properties by case-sensitive  string  identifiers: 

// Setting user-defined property
oProject.Properties["EPLAN.Project.UserSupplementaryField1"] = "test1";
// Getting user-defined property
string strValue = oProject.Properties["EPLAN.Project.UserSupplementaryField1"];

• UserDefinedPropertyDefinition  class extending  PropertyDefinition. The class allows creating custom property definitions or accessing information from existing ones:  

// Create a new property definition:
UserDefinedPropertyDefinition oUDPDProject = UserDefinedPropertyDefinition.Create(oCurrentProject, "API.Property.Project", UserDefinedPropertyDefinition.Enums.ClientType.Project);
oCurrentProject.Properties["API.Property.Project"] = "something";

var oCategory = oProject.Properties["EPLAN.Project.UserSupplementaryField1"].Category;  // Gets the category information
MultiLangString strDisplayedName = oProject.Properties["EPLAN.Project.UserSupplementaryField1"].DisplayedName; // Gets the name that is displayed in the GUI properties window

• Import / export property definitions (ExportPropertyDefinitions,  ImportPropertyDefinitions  from the  PrePlanningService  class) 

• The new  AnyPropertyId  constructor allowing to create an ID of a user-defined property:  

public AnyPropertyId(
    ref Eplan::EplApi::DataModel::Project pProject,
    ref System::String strUserDefiniedPropertyIdentName
);

• The  AnyPropertyId.AsString  propety to get the identifying name from  AnyPropertyId  which represents a user-defined property. 

• Actions that expect the ID of a property were extended to support also identifying names. Please go to the "API Reference" section for details.

Accessing default user-defined properties

Some user-defined properties are created by default, for example "EPLAN.Project.UserSupplementaryField1".

They have the same internal IDs as the old  *_CUSTOM_SUPPLEMENTARYFIELD*  properties (like "PROJ_CUSTOM_SUPPLEMENTARYFIELD01", etc). 

The use of old identifiers is still possible for compatibility reasons, but they generate warnings and will be removed in the future. 

Therefore, please replace them with the new IDs to avoid problems in forthcoming EPLAN versions: 

MultiLangString oMLS = oProject.Properties.PROJ_CUSTOM_SUPPLEMENTARYFIELD01;             // Old code, generates warning
MultiLangString oMLS = oProject.Properties["EPLAN.Project.UserSupplementaryField1"];     // New code

m_oTestProject.Properties.FUNC_ARTICLE_CUSTOM_SUPPLEMENTARYFIELD01[1] = strTestValue;     // Old code, generates warning:
ArticleReference oArticleReference = oProject.ArticleReferences[0];                       // New code
oArticleReference.Properties["EPLAN.PartRef.UserSupplementaryField1"] = strTestValue;
oArticleReference.StoreToObject();

Accessing user-defined properties through ArticleReference parent object

In the case of an  ArticleReference  object, when accessing a user-defined property through a parent  ArticleReference, it is necessary to add the  EPLAN.ArticleRef.  prefix to its identifying name. In addition, an index must be provided to indicate the position of the  ArticleReference  in the parent object.

var propertyValue1 = oArticleReference.Properties["UserProperty.1"].ToString();  // Accessing user-defined property from ArticleReference
var propertyValue2 = oArticleReference.Parent.Properties["EPLAN.ArticleRef.UserProperty.1"][1].ToString(); // Accessing user-defined property from a parent of the ArticleReference