Working with database. The Entity class
Glossary Item Box
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
NOTE
Use the “.NET class libraries of platform core” documentation to access the full list of the Entity class methods and properties, its parent classes and the implemented interfaces.
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 schemaUId schema set by the 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
| Property | Type | Description |
|---|---|---|
| ChangeType | EntityChangeType | The type of changing the entity status (added, modified, deleted, unchanged) |
| EntitySchemaManager | EntitySchemaManager | 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 | 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 | 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 | Instance of the object enumerations manager |
| ValueListSchemaManagerName | string | Name of the manager for object enumerations |
Methods
Table 2. Primary methods of the Entity class
| Methods | Description |
|---|---|
|
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<EntitySchemaColnmn> 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:
|
| bool FetchPrimaryColumnFromDB(object keyValue) | By the set condition, keyValue loads the object with 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:
|
|
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:
|
|
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:
|
| 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 SetDefColumnValue(string columnValueName, object defValue) void SetDefColumnValue(string columnValueName) |
Sets the property with the specified name to the default value |
| void SetDefColumnValues() | 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:
|
|
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
| Events | Description | Event data |
|---|---|---|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
Use cases
You can download the package with the configuration web serice implementing the below described cases using the following link.
Example 1
Receiving the value of the [City] schema column with [Name].
public string GetEntityColumnData() { var result = ""; // Creating a query to the "City" schema, adding the "Name" column to the query. var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "City"); var colName = esqResult.AddColumn("Name"); // Executing query to the database and receiving the object with the specified identifier. You can receive the object UId from a browser string with an open record edit page. var entity = esqResult.GetEntity(UserConnection, new Guid("100B6B13-E8BB-DF11-B00F-001D60E938C6")); // Receiving value of the object column. result += entity.GetColumnValue(colName.Name).ToString(); return result; }
Example 2
Receiving the collection of the [City] schema column names.
public IEnumerable<string> GetEntityColumns() { // Creating an object of the "City" schema data string (by schema identifier received from the database). var entity = new Entity(UserConnection, new Guid("5CA90B6A-93E7-4448-BEFE-AB5166EC2CFE")); // Receiving the object with the specified identifier from the darabase. You can receive the object UId from a browser string with an open record edit page. entity.FetchFromDB(new Guid("100B6B13-E8BB-DF11-B00F-001D60E938C6"),true); // Receiving the collecton of the object column names. var result = entity.GetColumnValueNames(); return result; }
Example 3
Deleting the [Order] schema record from the database.
public bool DeleteEntity() { // Creating a query to the "Order" schema, adding all schema columns to the query. var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Order"); esqResult.AddAllSchemaColumns(); // Executing query to the database and receiving the object with the specified identifier. You can receive the object UId from a browser string with an open record edit page. var entity = esqResult.GetEntity(UserConnection, new Guid("e3bfa32f-3fe9-4bae-9332-16c162c51e0d")); // Deleting the object from the database. entity.Delete(); // Verifying whether the object with the specified identifier exists in the database. var result = entity.ExistInDB(new Guid("e3bfa32f-3fe9-4bae-9332-16c162c51e0d")); return result; }
Example 4
Order status change.
public bool UpdateEntity() { // Creating a query to the "Order" schema, adding all schema columns to the query. var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Order"); esqResult.AddAllSchemaColumns(); // Executing the database query and receiving the object with the specified identifier. You can receive the object UId from a browser string with an open record edit page. var entity = esqResult.GetEntity(UserConnection, new Guid("58be5223-715d-4b16-a5c4-e3d4ec0412d9")); // Creating the object of the OrderStatus schema data string. var statusSchema = UserConnection.EntitySchemaManager.GetInstanceByName("OrderStatus"); var newStatus = statusSchema.CreateEntity(UserConnection); // Receiving the object with the specified name from the darabase. newStatus.FetchFromDB("Name", "4. Completed"); // Assigns a new value to the "StatusId" column. entity.SetColumnValue("StatusId", newStatus.GetTypedColumnValue<Guid>("Id")); // Saving the changed object in the database. var result = entity.Save(); return result; }
Example 5
Adding the city with the specified name with connecting it to the specified country.
public bool InsertEntity(string city, string country) { city = city ?? "unknown city"; country = country ?? "unknown country"; var citySchema = UserConnection.EntitySchemaManager.GetInstanceByName("City"); var entity = citySchema.CreateEntity(UserConnection); entity.FetchFromDB("Name", city); // Sets the default values to the object columns. entity.SetDefColumnValues(); var contryEntity = new Entity(UserConnection, new Guid("09FCE1F8-515C-4296-95CD-8CD93F79A6CF")); contryEntity.FetchFromDB("Name", country); // Assigns the passed city name to the "Name" column. entity.SetColumnValue("Name", city); // Assigns the UId of the passed country to the CountryId column. entity.SetColumnValue("CountryId", contryEntity.GetTypedColumnValue<Guid>("Id")); var result = entity.Save(); return result; }
