EPLAN API allows accessing object properties, i.e. characteristics which are visible in GUI in "Properties" dialog. 

This is possible through Properties property which is defined for almost all DataModel objects. 

The list of all available properties for a particular object, you can find 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, which loops over all string properties of a project: 

 string strTmp = string.Empty;
 PropertyValue oPropValue;
 // iterate over all project's 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's 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 .NET Framework type or Eplan API type (for example Eplan.EplApi.Base.MultiLangString). It can be done explicitly by 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 property value to non-matching type, for example MultiLangString to int. In such cases there will be a runtime warning generated (as Eplan system message) or an exception 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 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 

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 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 category information
 MultiLangString strDisplayedName = oProject.Properties["EPLAN.Project.UserSupplementaryField1"].DisplayedName; //gets name that is displayed in GUI properties window

- import/export property definitions (ExportPropertyDefinitions, ImportPropertyDefinitions from PrePlanningService class) 

- new AnyPropertyId constructor allowing creating ID of user defined property:  

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

- AnyPropertyId.AsString propety to get identifying name from AnyPropertyId which represents user-defined property 

- actions that expects id of a property were extend to support also identifying names. Please go to API Reference 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 old *_CUSTOM_SUPPLEMENTARYFIELD* properties (like "PROJ_CUSTOM_SUPPLEMENTARYFIELD01", etc). 

Using old identifiers is still possible for compatibility reasons, however generates warnings and will be removed in future. 

So please replace them with new IDs to unique 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 by ArticleReference parent object

In case of an ArticleReference object, when accessing user-defined property by a parent an ArticleReference, there is necessary to add 'EPLAN.ArticleRef.' prefix to its identifying name. Also there must by index provided which is position of an ArticleReference at a 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