The Entity class

Introduction

The Terrasoft.Core.Entities.Entity class is designed to provide access to an object that represents a record in the database table.

The “Terrasoft.Core.Entities.Entity“ class

Constructors

public Entity((UserConnection userConnection))

Creates a new Entity class instance for the set UserConnection.

---

public Entity((UserConnection userConnection, Guid schemaUId))

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

---

public Entity((Entity source))

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

---

Properties

Table 1. Primary properties of the Entity class

ChangeType

EntityChangeType

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

---

EntitySchemaManager

EntitySchemaManager

An instance of the entity schema manager.

---

EntitySchemaManagerName

string

Name of the entity schema manager.

---

HasColumnValues

bool

Determines whether an object has at least one column.

---

HierarchyColumnValue

Guid

Value of column of the parent record relationship for hierarchical objects.

---

InstanceUId

Guid

Object instance identifier.

---

IsDeletedFromDB

bool

Determines whether the object is deleted from the database.

---

IsInColumnValueChanged

bool

Determines whether the handling of the ColumnValueChanged event is performed.

---

IsInColumnValueChanging

bool

Determines whether the handling of the ColumnValueChanging event is performed.

---

IsInDefColumnValuesSet

bool

Determines whether the handling of the DefColumnValuesSet event is performed.

---

IsInDeleted

bool

Determines whether the handling of the Deleted event is performed.

---

IsInDeleting

bool

Determines whether the handling of the Deleting event is performed.

---

IsInInserted

bool

Determines whether the handling of the Inserted event is performed.

---

IsInInserting

bool

Determines whether the handling of the Inserting event is performed.

---

IsInLoaded

bool

Determines whether the handling of the Loaded event is performed.

---

IsInLoading

bool

Determines whether the handling of the Loading event is performed.

---

IsInSaved

bool

Determines whether the handling of the Saved event is performed.

---

IsInSaveError

bool

Determines whether the handling of the SaveError event is performed.

---

IsInSaving

bool

Determines whether the handling of the Saving event is performed.

---

IsInUpdated

bool

Determines whether the handling of the Updated event is performed.

---

IsInUpdating

bool

Determines whether the handling of the Updating event is performed.

---

IsInValidating

bool

Determines whether the handling of the Validating event is performed.

---

IsSchemaInitialized

bool

Determines whether the entity schema is initialized.

---

LicOperationPrefix

string

The prefix of the operation that is being licensed.

---

LoadState

EntityLoadState

State of the object loading.

---

PrimaryColumnValue

Guid

Initial column identifier.

---

PrimaryDisplayColumnValue

string

Initial column value for displaying.

---

Process

Process

The embedded process of an object.

---

Schema

EntitySchema

An instance of the entity schema.

---

SchemaName

string

Object schema name.

---

StoringState

StoringObjectState

Object status (modified, added, deleted, unchanged).

---

UseAdminRights

bool

Determines whether permissions will be taken into account when inserting, updating, deleting and receiving data.

---

UseDefRights

bool

Determines whether the default object permissions should be used.

---

UseLazyLoad

bool

Determines whether to use the initial lazy loading of object data.

---

UserConnection

UserConnection

User connection.

---

ValidationMessages

EntityValidationMessageCollection

Collection of the messages output when validating an object.

---

ValueListSchemaManager

ValueListSchemaManager

An instance of the object enumerations manager.

---

ValueListSchemaManagerName

string

Name of the manager for object enumerations.

---

Methods

Table 2. Primary methods of the Entity class

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

Sets the default permissions for the given object.

---

virtual object Clone(())

Creates a clone of the current Entity instance.

---

Insert CreateInsert((bool skipLookupColumnValues))

Creates a query to insert data.

---

Update CreateUpdate((bool skipLookupColumnValues))

Creates a query to update data.

---

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

Deletes the object record from the database. The keyValue parameter determines the initial key of a record.

---

bool DeleteWithCancelProcess(())

Deletes the object record from the database and cancels the launched process.

---

static Entity DeserializeFromJson((UserConnection userConnection, string jsonValue))

Creates an Entity type object using userConnection and populates the field values from the specified string of the JSON jsonValue format.

---

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

Determines whether a record matching the given condition of the conditionValue query to the conditionColumn object schema column or with the specified keyValue initial key exists in the database.

---

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))

By the specified condition, loads the object from the database.

Parameters:

• conditionColumn – the column, for which the selection condition is specified;
• conditionColumnName – the name of the column, for which the selection condition is specified;
• conditionValue – the value of the condition column for the selected data;
• columnsToFetch – the list of columns to be selected;
• columnNamesToFetch – the list of column names to be selected;
• conditions – set of conditions for filtering the selection of object records;
• keyValue – the key field value;
• useDisplayValues – indicates that the query returns the primary display values. If the parameter is true, the query will return the primary display values.

---

bool FetchPrimaryColumnFromDB((object keyValue))

By the set condition, keyValue loads the object with the initial column from the database.

---

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

By the set condition, loads an object with initial columns including the initial display column from the database.

---

byte[] GetBytesValue((string valueName))

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

---

IEnumerable<EntityColumnValue> GetChangedColumnValues(())

Returns the name collection of the object properties that have been modified.

---

string GetColumnDisplayValue((EntitySchemaColumn column))

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

---

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

Returns the previous value of the specified object property.

---

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

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

---

IEnumerable<string> GetColumnValueNames(())

Returns the collection of object column names.

---

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

Returns whether the specified property of an object is loaded.

---

virtual MemoryStream GetStreamValue((string valueName))

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

---

virtual TResult GetTypedColumnValue<TResult>((string valueName))
TResult GetTypedColumnValue<TResult>((EntitySchemaColumn column))

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

---

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.

---

virtual bool InsertToDB((bool skipLookupColumnValues, bool validateRequired))

Adds an entry of the current object to the database taking into account the passed parameters:

• skipLookupColumnValues – parameter that determines whether the columns of the lookup type are to be added to the database. If the parameter is true, the columns of the lookup type will not be added to the base. Default value – false;
• validateRequired – parameter that determines the necessity of validating the required values. Default value – true.

---

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

Determines whether the value of the object property with the specified name is loaded.

---

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 object with the passed data.

Parameters:

• dataRow – The System.Data.DataRow instance from which the data is loaded to the object;
• dataRow – The System.Data.IDataReader instance from which the data is loaded to the object;
• dataSource – The System.Object instance from which the data is loaded to the object;
• columnMap – object properties populated with data.

---

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:

• columnValueName – name of the object property;
• column – object schema column;
• dataReader – the System.Data.IDataReader instance from which the property value is loaded;
• fieldIndex – index of the field loaded from System.Data.IDataReader;
• binaryPackageSize – size of the loaded value;
• Value – value of the property that is being loaded.

---

static Entity Read((UserConnection userConnection, DataReader dataReader))

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

---

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

Reads data from the object schema and saves them in the specified object of the System.Data.IDataReader type.

---

void ResetColumnValues(())

Cancels changes for all object properties.

---

void ResetOldColumnValues(())

Reverts all object properties to previous values.

---

bool Save((bool validateRequired))

Saves the object to the database. The validateRequired parameter determines the necessity of validating the required values. Default value – true.

---

static string SerializeToJson((Entity entity))

Converts the entity object into a JSON format string.

---

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

Sets the passed value of the System.Byte type for the specified object property.

---

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

Sets the passed value and displayValue to the object property matching the specified schema column.

---

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

Sets the passed value to the specified schema column.

---

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

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

---

void SeddefColumnValues(())

Sets default values for all object properties.

---

bool SetStreamValue((string valueName, Stream value))

Sets the passed value of the System.IO.Stream type for the specified object property.

---

virtual bool UpdateInDB((bool validateRequired))

Updates the object record in the database. The validateRequired parameter determines the necessity of validating the required values. Default value – 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))

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

Parameters:

• dataWriter – instance of the Terrasoft.Common.DataWriter class that provides methods for sequential recording of values to the output stream;
• entity – value for record of the Entity type;
• propertyName – name of the object;
• couldConvertForXml – allows converting for XML-serialization.

---

void Write((DataWriter dataWriter, string propertyName))

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

---

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

Records to the output stream for the specified object schema.

---

Events

Table 3. The Entity class events

event EventHandler<EntityColumnAfterEventArgs> ColumnValueChanged

Event handler used after modifying the value of an entity column.

The event handler receives an argument of the EntityColumnAfterEventArgs type.

The EntityColumnAfterEventArgs properties that provide information referring to the event:

• ColumnValueName;
• DisplayColumnValueName.

---

event EventHandler<EntityColumnBeforeEventArgs> ColumnValueChanging

Event handler used before modifying the value of an entity column.

The event handler receives an argument of the EntityColumnBeforeEventArgs type.

The EntityColumnBeforeEventArgs properties that provide information referring to the event:

• ColumnStreamValue;
• ColumnValues;
• ColumnValueName;
• DisplayColumnValue;
• DisplayColumnValueName.

---

event EventHandler<EventArgs> DefColumnValuesSet

Event handler used after setting default values for the object fields.

---

event EventHandler<EntityAfterEventArgs> Deleted

Event handler used after deleting an object.

The event handler receives an argument of the EntityAfterEventArgs type.

The EntityAfterEventArgs properties that provide information referring to the event:

• ModifiedColumnValues;
• PrimaryColumnValue.

---

event EventHandler<EntityBeforeEventArgs> Deleting

Event handler used before deleting an object.

The event handler receives an argument of the EntityBeforeEventArgs type.

The EntityBeforeEventArgs properties that provide information referring to the event:

• AdditionalCondition;
• IsCanceled;
• KeyValue.

---

event EventHandler<EntityAfterEventArgs> Inserted

Event handler used after inserting an object.

The event handler receives an argument of the EntityAfterEventArgs type.

The EntityAfterEventArgs properties that provide information referring to the event:

• ModifiedColumnValues;
• PrimaryColumnValue.

---

event EventHandler<EntityBeforeEventArgs> Inserting

Event handler used before inserting an object.

The event handler receives an argument of the EntityBeforeEventArgs type.

The EntityBeforeEventArgs properties that provide information referring to the event:

• AdditionalCondition;
• IsCanceled;
• KeyValue.

---

event EventHandler<EntityAfterLoadEventArgs> Loaded

Event handler used after loading an object.

The event handler receives an argument of the EntityAfterLoadEventArgs type.

The EntityAfterLoadEventArgs properties that provide information referring to the event:

• ColumnMap;
• DataSource.

---

event EventHandler<EntityBeforeLoadEventArgs> Loading

Event handler used before loading an object.

The event handler receives an argument of the EntityBeforeLoadEventArgs type.

The EntityBeforeLoadEventArgs properties that provide information referring to the event:

• ColumnMap;
• DataSource;
• IsCanceled.

---

event EventHandler<EntityAfterEventArgs> Saved

Event handler used after saving an object.

The event handler receives an argument of the EntityAfterEventArgs type.

The EntityAfterEventArgs properties that provide information referring to the event:

• ModifiedColumnValues;
• PrimaryColumnValue.

---

event EventHandler<EntitySaveErrorEventArgs> SaveError

Event handler used when an error occurs while saving an object.

The event handler receives an argument of the EntitySaveErrorEventArgs type.

The EntitySaveErrorEventArgs properties that provide information referring to the event:

• Exception;
• IsHandled.

---

event EventHandler<EntityBeforeEventArgs> Saving

Event handler used before saving an object.

The event handler receives an argument of the EntityBeforeEventArgs type.

The EntityBeforeEventArgs properties that provide information referring to the event:

• AdditionalCondition;
• IsCanceled;
• KeyValue.

---

event EventHandler<EntityAfterEventArgs> Updated

Event handler used after updating an object.

The event handler receives an argument of the EntityAfterEventArgs type.

The EntityAfterEventArgs properties that provide information referring to the event:

• ModifiedColumnValues;
• PrimaryColumnValue.

---

event EventHandler<EntityBeforeEventArgs>Updating

Event handler used before updating an object.

The event handler receives an argument of the EntityBeforeEventArgs type.

The EntityBeforeEventArgs properties that provide information referring to the event:

• AdditionalCondition;
• IsCanceled;
• KeyValue.

---

event EventHandler<EntityValidationEventArgs> Validating

Event handler used when validating an object.

The event handler receives an argument of the EntityValidationEventArgs type.

The EntityValidationEventArgs properties that provide information referring to the event:

• Messages.

---

See also

• Examples of using the Delete class to erase data