Entity class

Level: advanced

Terrasoft.Core.Entities namespace.

The Terrasoft.Core.Entities.Entity class provides access to an entity that represents a record in the database table.

note

View the entire list of methods and properties of the Entity class, its parent classes, as well as the interfaces it implements, in the .NET classes reference.

Constructors

Entity(UserConnection userConnection)

Creates a new Entity class instance for the set UserConnection user connection.

Entity(UserConnection userConnection, Guid schemaUId)

Creates a new Entity class instance for the set UserConnection user connection and the schema set by the schemaUId identifier.

Entity(Entity source)

Creates a class instance that is a clone of the instance passed as an argument.

Properties

ChangeType EntityChangeType

The type of entity status change (added, modified, deleted, unchanged).

EntitySchemaManager EntitySchemaManager

An instance of the entity schema manager.

EntitySchemaManagerName string

The name of the entity schema manager.

HasColumnValues bool

Whether an entity has at least one column.

HierarchyColumnValue Guid

The value of the column that binds the parent record, for hierarchical entities.

InstanceUId Guid

The object instance identifier.

IsDeletedFromDB bool

Whether the object is deleted from the database.

IsInColumnValueChanged bool

Whether to handle the ColumnValueChanged event.

IsInColumnValueChanging bool

Whether to handle the ColumnValueChanging event.

IsInDefColumnValuesSet bool

Whether to handle the DefColumnValuesSet event.

IsInDeleted bool

Whether to handle the Deleted event.

IsInDeleting bool

Whether to handle the Deleting event.

IsInInserted bool

Whether to handle the Inserted event.

IsInInserting bool

Whether to handle the Inserting event.

IsInLoaded bool

Whether to hanlde the Loaded event.

IsInLoading bool

Whether to handle the Loading event.

IsInSaved bool

Whether to handle the Saved event.

IsInSaveError bool

Whether to handle the SaveError event.

IsInSaving bool

Whether to handle the Saving event.

IsInUpdated bool

Whether to handle the Updated event.

IsInUpdating bool

Whether to handle the Updating event.

IsInValidating bool

Whether to handle the Validating event.

IsSchemaInitialized bool

Whether the entity schema is initialized.

LicOperationPrefix string

The prefix of the operation to license.

LoadState EntityLoadState

The object load state.

PrimaryColumnValue Guid

The ID of the initial column.

PrimaryDisplayColumnValue string

The value to display in the initial column.

Process Process

The nested process of the entity.

Schema EntitySchema

An instance of the entity schema.

SchemaName string

The entity schema name.

StoringState StoringObjectState

The entity status (modified, added, deleted, unchanged).

UseAdminRights bool

Whether to apply permissions when inserting, updating, deleting, and retrieving data.

UseDefRights bool

Whether to use the default entity permissions.

UseLazyLoad bool

Whether to use the lazy initial loading of entity data.

UserConnection UserConnection

The user connection.

ValidationMessages EntityValidationMessageCollection

The message collection displayed when validating an entity.

ValueListSchemaManager ValueListSchemaManager

An instance of the entity enumerations manager.

ValueListSchemaManagerName string

The name of the entity enumerations manager.

Methods

void AddDefRights()
void AddDefRights(Guid primaryColumnValue)
void AddDefRights(IEnumerable<Guid> primaryColumnValues)

Sets the default permissions for the entity.

Parameters

primaryColumnValue	The ID of the access permission value.
primaryColumnValues	An array of IDs of the access permission values.

virtual object Clone()

Creates a clone of the current Entity instance.

Insert CreateInsert(bool skipLookupColumnValues)

Creates a query to add data to the database.

Parameters

skipLookupColumnValues

Whether to take the lookup columns into account while adding data. By default, false.

Update CreateUpdate(bool skipLookupColumnValues)

Creates a query to update data in the database.

Parameters

skipLookupColumnValues

Whether to add the columns of the lookup type to the database. If set to true, Creatio will not add the columns of the lookup type to the database. By default, false.

virtual bool Delete()
virtual bool Delete(object keyValue)

Deletes the entity record from the database.

Parameters

keyValue

The key field value.

bool DeleteWithCancelProcess()

Deletes the entity record from the database and cancels the started process.

static Entity DeserializeFromJson(UserConnection userConnection, string jsonValue)

Creates an Entity type entity using the userConnection user connection and populates the entity field values from the specified jsonValue JSON string.

Parameters

jsonValue	A JSON string.
userConnection	The user connection.

bool ExistInDB(EntitySchemaColumn conditionColumn, object conditionValue)
bool ExistInDB(string conditionColumnName, object conditionValue)
bool ExistInDB(object keyValue)
bool ExistInDB(Dictionary<string,object> conditions)

Whether the database contains a record that matches the given condition of the conditionValue query to the conditionColumn entity schema column or with the specified keyValue initial key.

Parameters

conditionColumn	The column for which to specify the selection condition.
conditionColumnName	The name of the column for which to specify the selection condition.
conditionValue	The value of the condition column for the selected data.
conditions	A set of conditions to filter the object record selection.
keyValue	The key field value.

bool FetchFromDB(EntitySchemaColumn conditionColumn, object conditionValue, bool useDisplayValues)
bool FetchFromDB(string conditionColumnName, object conditionValue, bool useDisplayValues)
bool FetchFromDB(object keyValue, bool useDisplayValues)
bool FetchFromDB(Dictionary<string,object> conditions, bool useDisplayValues)
bool FetchFromDB(EntitySchemaColumn conditionColumn, object conditionValue, IEnumerable<EntitySchemaColumn> columnsToFetch, bool useDisplayValues)
bool FetchFromDB(string conditionColumnName, object conditionValue, IEnumerable<string>columnNamesToFetch, bool useDisplayValues)

Loads the object from the database by the specified condition.

Parameters

conditionColumn	The column for which to specify the selection condition.
conditionColumnName	The name of the column for which to specify the selection condition.
conditionValue	The value of the condition column for the selected data.
columnsToFetch	The list of columns to select.
columnNamesToFetch	The list of column names to select.
conditions	A set of conditions to filter the object record selection.
keyValue	The key field value.
useDisplayValues	Indicates that the query returns the initial displayed values. If set to true, the query will return the initial displayed values.

bool FetchPrimaryColumnFromDB(object keyValue)

Loads the object with the initial column from the database by the set keyValue condition.

Parameters

keyValue

The key field value.

bool FetchPrimaryInfoFromDB(EntitySchemaColumn conditionColumn, object conditionValue)
bool FetchPrimaryInfoFromDB(string conditionColumnName, object conditionValue)

Loads a database object with initial columns, including the initial displayed column, by the set condition.

Parameters

conditionColumn	The column for which to specify the selection condition.
conditionColumnName	The name of the column for which to specify the selection condition.
conditionValue	The value of the condition column for the selected data.

byte[] GetBytesValue(string valueName)

Returns the value of the specified entity column as a byte array.

Parameters

valueName

The name of the entity column.

IEnumerable<EntityColumnValue> GetChangedColumnValues()

Returns the name collection of the object properties that were modified.

string GetColumnDisplayValue(EntitySchemaColumn column)

Returns the value for the display of the object property that matches the specified entity schema column.

Parameters

column

A specific entity schema column.

object GetColumnOldValue(string valueName)
object GetColumnOldValue(EntitySchemaColumn column)

Returns the previous value of the specified entity property.

Parameters

column	A specific entity schema column.
valueName	The name of the entity column.

virtual object GetColumnValue(string valueName)
virtual object GetColumnValue(EntitySchemaColumn column)

Returns the value of the entity column with the specified name that matches the passed entity schema column.

Parameters

column	A specific entity schema column.
valueName	The name of the entity column.

IEnumerable<string> GetColumnValueNames()

Returns the collection of entity column names.

virtual bool GetIsColumnValueLoaded(string valueName)
bool GetIsColumnValueLoaded(EntitySchemaColumn column)

Returns the flag that determines whether the specified entity property is loaded.

Parameters

column	A specific entity schema column.
valueName	The name of the entity column.

virtual MemoryStream GetStreamValue(string valueName)

Returns the value of the passed entity schema column converted into the System.IO.MemoryStream type instance.

Parameters

valueName

The name of the entity column.

TResult GetTypedColumnValue<tresult>(EntitySchemaColumn column)

Returns the typed value of the entity property that matches the specified column of the entity schema.

Parameters

column

A specific entity schema column.

TResult GetTypedOldColumnValue<tresult>(string valueName)
TResult GetTypedOldColumnValue<tresult>(EntitySchemaColumn column)

Returns the typed previous value of the entity property that matches the specified column of the entity schema.

Parameters

column	A specific entity schema column.
valueName	The name of the entity column.

virtual bool InsertToDB(bool skipLookupColumnValues, bool validateRequired)

Adds a record of the current entity to the database.

Parameters

skipLookupColumnValues	Whether to add the columns of the lookup type to the database. If set to true, Creatio will not add the columns of the lookup type to the database. By default, false.
validateRequired	Whether to validate the required values. By default, true.

bool IsColumnValueLoaded(string valueName)
bool IsColumnValueLoaded(EntitySchemaColumn column)

Whether the value of the entity property with the specified name is loaded.

Parameters

column	A specific entity schema column.
valueName	The name of the entity column.

virtual bool Load(DataRow dataRow)
virtual bool Load(DataRow dataRow, Dictionary<string,string> columnMap)
virtual bool Load(IDataReader dataReader)
virtual bool Load(IDataReader dataReader, IDictionary<string,string> columnMap)
virtual bool Load(object dataSource)
virtual bool Load(object dataSource, IDictionary<string,string> columnMap)

Populates the entity with the passed data.

Parameters

columnMap	The entity properties to populate with data.
dataRow	A System.Data.DataRow instance from which to load the data to the entity.
dataReader	A System.Data.IDataReader instance from which to load the data to the entity.
dataSource	A System.Object instance from which to load the data to the entity.

void LoadColumnValue(string columnValueName, IDataReader dataReader, int fieldIndex, int binaryPackageSize)
void LoadColumnValue(string columnValueName, IDataReader dataReader, int fieldIndex)
void LoadColumnValue(string columnValueName, object value)
void LoadColumnValue(EntitySchemaColumn column, object value)

Loads the value from the passed instance for the property with the specified name.

Parameters

binaryPackageSize	The size of the loaded value.
column	The entity schema column.
columnValueName	The entity property name.
dataReader	A System.Data.IDataReader instance from which to load the property value.
fieldIndex	The index of the field loaded from System.Data.IDataReader.
value	The loaded value of the property.

static Entity Read(UserConnection userConnection, DataReader dataReader)

Returns the current property value of the Entity type from the input stream.

Parameters

dataReader	A System.Data.IDataReader instance from which to load the property value.
userConnection	The user connection.

void ReadData(DataReader reader)
void ReadData(DataReader reader, EntitySchema schema)

Reads data from the entity schema and saves the data to the specified object of the System.Data.IDataReader type.

Parameters

reader	A System.Data.IDataReader instance to which to load the entity schema data.
schema	The entity schema.

void ResetColumnValues();

Cancels the changes for all entity properties.

void ResetOldColumnValues();

Reverts all entity properties to previous values.

bool Save(bool validateRequired)

Saves the entity to the database.

Parameters

validateRequired

Whether to validate the required values. By default, true.

static string SerializeToJson(Entity entity)

Converts the entity object into a JSON string.

Parameters

entity

The Entity instance.

virtual void SetBytesValue(string valueName, byte[] streamBytes)

Sets the specified entity property to the passed value of the System.Byte type.

Parameters

streamBytes	A value of the System.Byte type set for the specified entity column.
valueName	The name of the entity column.

bool SetColumnBothValues(EntitySchemaColumn column, object value, string displayValue)
bool SetColumnBothValues(string columnValueName, object value, string displayColumnValueName, string displayValue)

Sets the entity property that matches the specified schema column to passed value and displayValue.

Parameters

column	The entity schema column.
displayValue	The loaded value for display.
displayColumnValueName	The name of the column that contains the value for display.
value	The loaded value of the column.

bool SetColumnValue(string valueName, object value)
bool SetColumnValue(EntitySchemaColumn column, object value)

Sets the specified schema column to the passed value.

Parameters

column	The entity schema column.
value	The loaded value of the column.
valueName	The name of the entity column.

void SeddefColumnValue(string columnValueName, object defValue)
void SeddefColumnValue(string columnValueName)

Sets the property with the specified name to the default value.

Parameters

columnValueName	The name of the entity column.
defValue	The default value.

void SeddefColumnValues();

Sets default values for all entity properties.

bool SetStreamValue(string valueName, Stream value)

Sets the specified entity property to the passed value of the System.IO.Stream type.

Parameters

value	The loaded value of the column.
valueName	The name of the entity column.

virtual bool UpdateInDB(bool validateRequired)

Updates the entity record in the database.

Parameters

validateRequired

Whether to validate the required values. By default, true.

bool Validate()

Verifies if the required fields are populated.

static void Write(DataWriter dataWriter, Entity entity, string propertyName)
static void Write(DataWriter dataWriter, Entity entity, string propertyName, bool couldConvertForXml)

Writes the value of the Entity type to the output stream with the specified name.

Parameters

couldConvertForXml	Allow converting for XML serialization.
dataWriter	An instance of the Terrasoft.Common.DataWriter class that provides methods for writing values to the output stream sequentially.
entity	A value for a record of the Entity type.
propertyName	The entity name.

void Write(DataWriter dataWriter, string propertyName)

Writes the data to the output stream with the specified name.

Parameters

dataWriter	An instance of the Terrasoft.Common.DataWriter class that provides methods for writing values to the output stream sequentially.
propertyName	The property name.

void WriteData(DataWriter writer)
void WriteData(DataWriter writer, EntitySchema schema)

Writes to the output stream for the specified or current entity schema.

Parameters

schema	The entity schema.
writer	An instance of the Terrasoft.Common.DataWriter class that provides methods for writing values to the output stream sequentially.

Events

event EventHandler<EntityColumnAfterEventArgs> ColumnValueChanged

Event handler used after modifying the entity column value.

The event handler receives an argument of the EntityColumnAfterEventArgs type.

The EntityColumnAfterEventArgs properties that provide information relevant to the event:

• ColumnValueName
• DisplayColumnValueName

event EventHandler<EntityColumnBeforeEventArgs> ColumnValueChanging

Event handler used before modifying the entity column value.

The event handler receives an argument of the EntityColumnBeforeEventArgs type.

The EntityColumnBeforeEventArgs properties that provide information relevant to the event:

• ColumnStreamValue
• ColumnValue
• ColumnValueName
• DisplayColumnValue
• DisplayColumnValueName

event EventHandler<EventArgs> DefColumnValuesSet

Event handler used after setting default entity field values.

event EventHandler<EntityAfterEventArgs> Deleted

Event handler used after deleting an entity.

The event handler receives an argument of the EntityAfterEventArgs type.

The EntityAfterEventArgs properties that provide information relevant to the event:

• ModifiedColumnValues
• PrimaryColumnValue

event EventHandler<EntityBeforeEventArgs> Deleting

Event handler used before deleting an entity.

The event handler receives an argument of the EntityBeforeEventArgs type.

The EntityBeforeEventArgs properties that provide information relevant to the event:

• AdditionalCondition
• IsCanceled
• KeyValue

event EventHandler<EntityAfterEventArgs> Inserted

Event handler used after inserting an entity.

The event handler receives an argument of the EntityAfterEventArgs type.

The EntityAfterEventArgs properties that provide information relevant to the event:

• ModifiedColumnValues
• PrimaryColumnValue

event EventHandler<EntityBeforeEventArgs> Inserting

Event handler used before inserting an entity.

The event handler receives an argument of the EntityBeforeEventArgs type.

The EntityBeforeEventArgs properties that provide information relevant to the event:

• AdditionalCondition
• IsCanceled
• KeyValue

event EventHandler<EntityAfterLoadEventArgs> Loaded

Event handler used after loading an entity.

The event handler receives an argument of the EntityAfterLoadEventArgs type.

The EntityAfterLoadEventArgs properties that provide information relevant to the event:

• ColumnMap
• DataSource

event EventHandler<EntityBeforeLoadEventArgs> Loading

Event handler used before loading an entity.

The event handler receives an argument of the EntityBeforeLoadEventArgs type.

The EntityBeforeLoadEventArgs properties that provide information relevant to the event:

• ColumnMap
• DataSource
• IsCanceled

event EventHandler<EntityAfterEventArgs> Saved

Event handler used after saving an entity.

The event handler receives an argument of the EntityAfterEventArgs type.

The EntityAfterEventArgs properties that provide information relevant to the event:

• ModifiedColumnValues
• PrimaryColumnValue

event EventHandler<EntitySaveErrorEventArgs> SaveError

Event handler used if an error occurs while saving an entity.

The event handler receives an argument of the EntitySaveErrorEventArgs type.

The EntitySaveErrorEventArgs properties that provide information relevant to the event:

• Exception
• IsHandled

event EventHandler<EntityBeforeEventArgs> Saving

Event handler used before saving an entity.

The event handler receives an argument of the EntityBeforeEventArgs type.

The EntityBeforeEventArgs properties that provide information relevant to the event:

• AdditionalCondition
• IsCanceled
• KeyValue

event EventHandler<EntityAfterEventArgs> Updated

Event handler used after updating an entity.

The event handler receives an argument of the EntityAfterEventArgs type.

The EntityAfterEventArgs properties that provide information relevant to the event:

• ModifiedColumnValues
• PrimaryColumnValue

event EventHandler<EntityBeforeEventArgs>Updating

Event handler used before updating an entity.

The event handler receives an argument of the EntityBeforeEventArgs type.

The EntityBeforeEventArgs properties that provide information relevant to the event:

• AdditionalCondition
• IsCanceled
• KeyValue

event EventHandler<EntityValidationEventArgs> Validating

Event handler used when validating an entity.

The event handler receives an argument of the EntityValidationEventArgs type.

The EntityValidationEventArgs properties that provide information relevant to the event:

• Messages