Документация

Creatio development guide
PDF
Это документация Creatio версии 7.15.0. Мы рекомендуем использовать новую версию документации.

Работа с сущностью базы данных. Класс Entity

Glossary Item Box

Общие сведения

Класс Terrasoft.Core.Entities.Entity предназначен для доступа к объекту, который представляет собой запись в таблице базы данных.

Класс Terrasoft.Core.Entities.Entity

ВАЖНО

НА ЗАМЕТКУ

Полный перечень методов и свойств класса Entity, его родительских классов, а также реализуемых им интерфейсов, можно найти в документации ".NET библиотеки классов ядра платформы".

Конструкторы

  • public Entity(UserConnection userConnection) — создает новый экземпляр класса Entity для заданного пользовательского подключения UserConnection.
  • public Entity(UserConnection userConnection, Guid schemaUId) — создает новый экземпляр класса Entity для заданного пользовательского подключения UserConnection и схемы заданной идентификатором schemaUId.
  • public Entity(Entity source) — создает экземпляр класса, являющийся клоном экземпляра, переданного в качестве аргумента.

Свойства

Табл. 1. — Основные свойства класса Entity

Свойство Тип Описание
ChangeType EntityChangeType Тип изменения состояния объекта (добавлен, изменен, удален, без изменений).
EntitySchemaManager EntitySchemaManager Экземпляр менеджера схемы объекта.
EntitySchemaManagerName string Имя менеджера схемы объекта.
HasColumnValues bool Определяет, имеет ли объект хотя бы одну колонку.
HierarchyColumnValue Guid Значение колонки связи с родительской записью для иерархических объектов.
InstanceUId Guid Идентификатор экземпляра объекта.
IsDeletedFromDB bool Определяет, удален ли объект из базы данных.
IsInColumnValueChanged bool Определяет, выполняется ли обработка события ColumnValueChanged.
IsInColumnValueChanging bool Определяет, выполняется ли обработка события ColumnValueChanging.
IsInDefColumnValuesSet bool Определяет, выполняется ли обработка события DefColumnValuesSet.
IsInDeleted bool Определяет, выполняется ли обработка события Deleted.
IsInDeleting bool Определяет, выполняется ли обработка события Deleting.
IsInInserted bool Определяет, выполняется ли обработка события Inserted.
IsInInserting bool Определяет, выполняется ли обработка события Inserting.
IsInLoaded bool Определяет, выполняется ли обработка события Loaded.
IsInLoading bool Определяет, выполняется ли обработка события Loading.
IsInSaved bool Определяет, выполняется ли обработка события Saved.
IsInSaveError bool Определяет, выполняется ли обработка события SaveError.
IsInSaving bool Определяет, выполняется ли обработка события Saving.
IsInUpdated bool Определяет, выполняется ли обработка события Updated.
IsInUpdating bool Определяет, выполняется ли обработка события Updating.
IsInValidating bool Определяет, выполняется ли обработка события Validating.
IsSchemaInitialized bool Определяет, является ли схема объекта проинициализированной.
LicOperationPrefix string Префикс лицензируемой операции.
LoadState EntityLoadState Состояние загрузки объекта.
PrimaryColumnValue Guid Идентификатор первичной колонки.
PrimaryDisplayColumnValue string Значение для отображения первичной колонки.
Process Process Встроенный процесс объекта.
Schema EntitySchema Экземпляр схемы объекта.
SchemaName string Имя схемы объекта.
StoringState StoringObjectState Состояние объекта (изменен, добавлен, удален, без изменений).
UseAdminRights bool Определяет, будут ли учитываться права при вставке, обновлении, удалении и получении данных.
UseDefRights bool Определяет, использовать ли права по умолчанию на объект.
UseLazyLoad bool Определяет, использовать ли ленивую первоначальную загрузку данных объекта.
UserConnection UserConnection Пользовательское подключение.
ValidationMessages EntityValidationMessageCollection Коллекция сообщений, выводимых при проверке объекта.
ValueListSchemaManager ValueListSchemaManager Экземпляр менеджера перечислений объекта.
ValueListSchemaManagerName string Имя менеджера перечислений объекта.

Методы

Табл. 2. — Основные методы класса Entity

Методы Описание

void AddDefRights()

void AddDefRights(Guid primaryColumnValue)

void AddDefRights(IEnumerable<Guid> primaryColumnValues)

 Для данного объекта устанавливает права по умолчанию.
virtual object Clone() Создает клон текущего экземпляра Entity.
Insert CreateInsert(bool skipLookupColumnValues) Создает запрос на добавление данных в базу.
Update CreateUpdate(bool skipLookupColumnValues) Создает запрос на обновление данных в базе.

virtual bool Delete()

virtual bool Delete(object keyValue)

 Удаляет из базы данных запись объекта. Параметр keyValue определяет первичный ключ записи.
bool DeleteWithCancelProcess() Удаляет из базы данных запись объекта и отменяет запущенный процесс.
static Entity DeserializeFromJson(UserConnection userConnection, string jsonValue) Создает объект типа Entity, используя пользовательское подключение userConnection, и заполняет значения его полей из указанной строки формата JSON jsonValue.

bool ExistInDB(EntitySchemaColumn conditionColumn, object conditionValue)

bool ExistInDB(string conditionColumnName, object conditionValue)

bool ExistInDB(object keyValue)

bool ExistInDB(Dictionary<string,object> conditions)

 Определяет, существует ли в базе данных запись, отвечающая заданному условию запроса conditionValue к заданной колонке схемы объекта conditionColumn либо с заданным первичным ключом keyValue.

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)

По заданному условию загружает объект из базы данных.

Параметры:

  • conditionColumn — колонка, для которой задается условие выборки;
  • conditionColumnName — название колонки, для которой задается условие выборки;
  • conditionValue — значение колонки условия для выбираемых данных;
  • columnsToFetch — список колонок, которые будут выбраны;
  • columnNamesToFetch — список названий колонок, которые будут выбраны;
  • conditions — набор условий фильтрации выборки записей объекта;
  • keyValue — значение ключевого поля;
  • useDisplayValues — признак получения в запросе первичных отображаемых значений. Если параметр равен true, в запросе будут возвращены первичные отображаемые значения.
bool FetchPrimaryColumnFromDB(object keyValue) По заданному условию keyValue загружает из базы данных объект с первичной колонкой.

bool FetchPrimaryInfoFromDB(EntitySchemaColumn conditionColumn, object conditionValue)

bool FetchPrimaryInfoFromDB(string conditionColumnName, object conditionValue)

 По заданному условию загружает из базы данных объект с первичными колонками, включая колонку, первичную для отображения.
byte[] GetBytesValue(string valueName) Возвращает значение заданной колонки объекта в виде массива байт.
IEnumerable<EntityColumnValue> GetChangedColumnValues() Возвращает коллекцию имен колонок объекта, которые были изменены.
string GetColumnDisplayValue(EntitySchemaColumn column) Возвращает значение для отображения свойства объекта, соответствующее заданной колонке схемы объекта.

object GetColumnOldValue(string valueName)

object GetColumnOldValue(EntitySchemaColumn column)

 Возвращает предыдущее значение заданного свойства объекта.

virtual object GetColumnValue(string valueName)

virtual object GetColumnValue(EntitySchemaColumn column)

 Возвращает значение колонки объекта с заданным именем, cоответствующее переданной колонке схемы объекта.
IEnumerable<string> GetColumnValueNames() Возвращает коллекцию имен колонок объекта.

virtual bool GetIsColumnValueLoaded(string valueName)

bool GetIsColumnValueLoaded(EntitySchemaColumn column)

 Возвращает признак, определяющий, загружено ли заданное свойство объекта.
virtual MemoryStream GetStreamValue(string valueName) Возвращает преобразованное в экземпляр типа System.IO.MemoryStream значение переданной колонки схемы объекта.

virtual TResult GetTypedColumnValue<TResult>(string valueName)

TResult GetTypedColumnValue<TResult>(EntitySchemaColumn column)

 Возвращает типизированное значение свойства объекта, соответствующее заданной колонке схемы объекта.

TResult GetTypedOldColumnValue<TResult>(string valueName)

TResult GetTypedOldColumnValue<TResult>(EntitySchemaColumn column)

 Возвращает типизированное предыдущее значение свойства объекта, соответствующее заданной колонке схемы объекта.
virtual bool InsertToDB(bool skipLookupColumnValues, bool validateRequired)

Добавляет запись текущего объекта в базу данных с учетом переданных параметров:

  • skipLookupColumnValues — параметр, определяющий необходимость добавления в базу данных колонок типа справочник. Если параметр равен true, то колонки типа справочник не будут добавлены в базу. Значение по умолчанию — false.
  • validateRequired — параметр, определяющий необходимость проверки заполнения обязательных значений. Значение по умолчанию — true.

bool IsColumnValueLoaded(string valueName)

bool IsColumnValueLoaded(EntitySchemaColumn 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)

Заполняет объект переданными данными.

Параметры:

  • dataRow — экземпляр System.Data.DataRow, из которого загружаются данные в объект;
  • dataReader — экземпляр System.Data.IDataReader, из которого загружаются данные;
  • dataSource — экземпляр System.Object, из которого загружаются данные;
  • columnMap — свойства объекта, заполняемые данными.

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)

Для свойства с заданным именем загружает его значение из переданного экземпляра.

Параметры:

  • columnValueName — имя свойства объекта;
  • column — колонка схемы объекта;
  • dataReader — экземпляр System.Data.IDataReader, из которого загружается значение свойства;
  • fieldIndex — индекс загружаемого из System.Data.IDataReader поля;
  • binaryPackageSize — размер загружаемого значения;
  • value — загружаемое значение свойства.
static Entity Read(UserConnection userConnection, DataReader dataReader) Возвращает значение текущего свойства типа Entity из потока ввода.

void ReadData(DataReader reader)

void ReadData(DataReader reader, EntitySchema schema)

 Считывает данные из схемы объекта в заданный объект типа System.Data.IDataReader.
void ResetColumnValues() Для всех свойств объекта отменяет изменения.
void ResetOldColumnValues() Для всех свойств объекта отменяет изменения, устанавливая предыдущее значение.
bool Save(bool validateRequired) Сохраняет объект в базе данных. Параметр validateRequired определяет необходимость проверки заполнения обязательных значений. Значение по умолчанию — true.
static string SerializeToJson(Entity entity) Преобразует объект entity в строку формата JSON.
virtual void SetBytesValue(string valueName, byte[] streamBytes) Устанавливает для заданного свойства объекта переданное значение типа System.Byte.

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

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

Устанавливает свойству объекта, соответствующему заданной колонке схемы, переданные значение value и значение для отображения displayValue.

bool SetColumnValue(string valueName, object value)

bool SetColumnValue(EntitySchemaColumn column, object value)

Устанавливает заданной колонке схемы переданное значение value.

void SetDefColumnValue(string columnValueName, object defValue)

void SetDefColumnValue(string columnValueName)

Устанавливает значение по умолчанию свойству с заданным именем.
void SetDefColumnValues() Для всех свойств объекта устанавливает значения по умолчанию.
bool SetStreamValue(string valueName, Stream value) Устанавливает для заданного свойства объекта переданное значение типа System.IO.Stream.
virtual bool UpdateInDB(bool validateRequired) Обновляет запись объекта в базе данных. Параметр validateRequired определяет необходимость проверки заполнения обязательных значений. Значение по умолчанию — true.
bool Validate() Проверяет заполнение обязательных полей.

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

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

Осуществляет запись значения типа Entity в поток вывода с заданными именем.

Параметры:

  • dataWriter — экземпляр класса Terrasoft.Common.DataWriter, предоставляющий методы последовательной записи значений в поток вывода;
  • entity — значение для записи типа Entity;
  • propertyName — имя объекта;
  • couldConvertForXml — разрешить преобразование для xml-сериализации.

void Write(DataWriter dataWriter, string propertyName)

 Осуществляет запись значения типа Entity в поток вывода с заданными именем.

void WriteData(DataWriter writer)

void WriteData(DataWriter writer, EntitySchema schema)

 Осуществляет запись в поток вывода для указанной либо текущей схемы объекта.

События

Табл. 3. — События класса Entity

События Описание Данные события
event EventHandler<EntityColumnAfterEventArgs> ColumnValueChanged Обработчик события, возникающего после изменения значения колонки объекта.

Обработчик события получает аргумент типа EntityColumnAfterEventArgs.

Свойства EntityColumnAfterEventArgs предоставляющие сведения, относящиеся к событию:

  • ColumnValueName;
  • DisplayColumnValueName.
event EventHandler<EntityColumnBeforeEventArgs> ColumnValueChanging Обработчик события, возникающего перед изменением значения колонки объекта.

Обработчик события получает аргумент типа EntityColumnBeforeEventArgs.

Свойства EntityColumnBeforeEventArgs предоставляющие сведения, относящиеся к событию:

  • ColumnStreamValue;
  • ColumnValue;
  • ColumnValueName;
  • DisplayColumnValue;
  • DisplayColumnValueName.
event EventHandler<EventArgs> DefColumnValuesSet Обработчик события, возникающего после установки значений по умолчанию полей объекта.
event EventHandler<EntityAfterEventArgs> Deleted Обработчик события, возникающего после удаления объекта.

Обработчик события получает аргумент типа EntityAfterEventArgs.

Свойства EntityAfterEventArgs предоставляющие сведения, относящиеся к событию:

  • ModifiedColumnValues;
  • PrimaryColumnValue.
event EventHandler<EntityBeforeEventArgs> Deleting Обработчик события, возникающего перед удалением объекта.

Обработчик события получает аргумент типа EntityBeforeEventArgs.

Свойства EntityBeforeEventArgs предоставляющие сведения, относящиеся к событию:

  • AdditionalCondition;
  • IsCanceled;
  • KeyValue.
event EventHandler<EntityAfterEventArgs> Inserted Обработчик события, возникающего после вставки объекта.

Обработчик события получает аргумент типа EntityAfterEventArgs.

Свойства EntityAfterEventArgs предоставляющие сведения, относящиеся к событию:

  • ModifiedColumnValues;
  • PrimaryColumnValue.
event EventHandler<EntityBeforeEventArgs> Inserting Обработчик события, возникающего перед вставкой объекта.

Обработчик события получает аргумент типа EntityBeforeEventArgs.

Свойства EntityBeforeEventArgs предоставляющие сведения, относящиеся к событию:

  • AdditionalCondition;
  • IsCanceled;
  • KeyValue.
event EventHandler<EntityAfterLoadEventArgs> Loaded Обработчик события, возникающего после загрузки объекта.

Обработчик события получает аргумент типа EntityAfterLoadEventArgs.

Свойства EntityAfterLoadEventArgs предоставляющие сведения, относящиеся к событию:

  • ColumnMap;
  • DataSource.
event EventHandler<EntityBeforeLoadEventArgs> Loading Обработчик события, возникающего перед загрузкой объекта.

Обработчик события получает аргумент типа EntityBeforeLoadEventArgs.

Свойства EntityBeforeLoadEventArgs предоставляющие сведения, относящиеся к событию:

  • ColumnMap;
  • DataSource;
  • IsCanceled.
event EventHandler<EntityAfterEventArgs> Saved Обработчик события, возникающего после сохранения объекта.

Обработчик события получает аргумент типа EntityAfterEventArgs.

Свойства EntityAfterEventArgs предоставляющие сведения, относящиеся к событию:

  • ModifiedColumnValues;
  • PrimaryColumnValue.
event EventHandler<EntitySaveErrorEventArgs> SaveError Обработчик события, возникающего при ошибке сохранения объекта.

Обработчик события получает аргумент типа EntitySaveErrorEventArgs.

Свойства EntitySaveErrorEventArgs предоставляющие сведения, относящиеся к событию:

  • Exception;
  • IsHandled.
event EventHandler<EntityBeforeEventArgs> Saving Обработчик события, возникающего перед сохранением объекта.

Обработчик события получает аргумент типа EntityBeforeEventArgs.

Свойства EntityBeforeEventArgs предоставляющие сведения, относящиеся к событию:

  • AdditionalCondition;
  • IsCanceled;
  • KeyValue.
event EventHandler<EntityAfterEventArgs> Updated Обработчик события, возникающего после обновления объекта.

Обработчик события получает аргумент типа EntityAfterEventArgs.

Свойства EntityAfterEventArgs предоставляющие сведения, относящиеся к событию:

  • ModifiedColumnValues;
  • PrimaryColumnValue.
event EventHandler<EntityBeforeEventArgs>Updating Обработчик события, возникающего перед обновлением объекта.

Обработчик события получает аргумент типа EntityBeforeEventArgs.

Свойства EntityBeforeEventArgs предоставляющие сведения, относящиеся к событию:

  • AdditionalCondition;
  • IsCanceled;
  • KeyValue.
event EventHandler<EntityValidationEventArgs> Validating Обработчик события, возникающего при проверке объекта.

Обработчик события получает аргумент типа EntityValidationEventArgs.

Свойства EntityValidationEventArgs предоставляющие сведения, относящиеся к событию:

  • Messages.

Примеры использования

Пакет с конфигурационным веб-сервисом, реализующим приведенные ниже примеры, можно скачать по ссылке.

Пример 1

Получение значения колонки схемы [City] с именем [Name].

public string GetEntityColumnData()
{
    var result = "";
    // Создание запроса к схеме City, добавление в запрос колонки Name.
    var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "City");
    var colName = esqResult.AddColumn("Name");
    // Выполнение запроса к базе данных и получение объекта с заданным идентификатором. UId объекта можно получить из строки навигации браузера с открытой страницей редактирования записи раздела.
    var entity = esqResult.GetEntity(UserConnection, new Guid("100B6B13-E8BB-DF11-B00F-001D60E938C6"));
    // Получение значения колонки объекта.
    result += entity.GetColumnValue(colName.Name).ToString();
    return result;
}

Пример 2

Получение коллекции имен колонок схемы [City].

public IEnumerable<string> GetEntityColumns()
{
    // Создание объекта строки данных схемы City (по идентификатору схемы, полученному из базы данных).
    var entity = new Entity(UserConnection, new Guid("5CA90B6A-93E7-4448-BEFE-AB5166EC2CFE"));
    // Получение из базы данных объекта с заданным идентификатором. UId объекта можно получить из строки навигации браузера с открытой страницей редактирования записи раздела.
    entity.FetchFromDB(new Guid("100B6B13-E8BB-DF11-B00F-001D60E938C6"),true);
    // Получение коллекции имен колонок объекта.
    var result = entity.GetColumnValueNames();
    return result;
}

Пример 3

Удаление из базы записи схемы [Order].

public bool DeleteEntity()
{
    // Создание запроса к схеме Order, добавление в запрос всех колонок схемы.
    var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Order");
    esqResult.AddAllSchemaColumns();
    // Выполнение запроса к базе данных и получение объекта с заданным идентификатором. UId объекта можно получить из строки навигации браузера с открытой страницей редактирования записи раздела.
    var entity = esqResult.GetEntity(UserConnection, new Guid("e3bfa32f-3fe9-4bae-9332-16c162c51e0d"));
    // Удаление объекта из базы данных.
    entity.Delete();
    // Проверка, существует ли в базе данных объект с заданным идентификатором.
    var result = entity.ExistInDB(new Guid("e3bfa32f-3fe9-4bae-9332-16c162c51e0d"));
    return result;
}

Пример 4

Изменение статуса заказа.

public bool UpdateEntity()
{
    // Создание запроса к схеме Order, добавление в запрос всех колонок схемы.
    var esqResult = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Order");
    esqResult.AddAllSchemaColumns();
    // Выполнение запроса к базе данных и получение объекта с заданным идентификатором. UId объекта можно получить из строки навигации браузера с открытой страницей редактирования записи раздела.
    var entity = esqResult.GetEntity(UserConnection, new Guid("58be5223-715d-4b16-a5c4-e3d4ec0412d9"));
    // Создание объекта строки данных схемы OrderStatus.
    var statusSchema = UserConnection.EntitySchemaManager.GetInstanceByName("OrderStatus");
    var newStatus = statusSchema.CreateEntity(UserConnection);
    // Получение из базы данных объекта c заданным названием.
    newStatus.FetchFromDB("Name", "4. Completed");
    // Присваивает колонке StatusId новое значение.
    entity.SetColumnValue("StatusId", newStatus.GetTypedColumnValue<Guid>("Id"));
    // Сохранение измененного объекта в базе данных.
    var result = entity.Save();
    return result;
}

Пример 5

Добавление города с указанным названием, привязав его к указанной стране.

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);
    // Устанавливает для колонок объекта значения по умолчанию.
    entity.SetDefColumnValues();
    var contryEntity = new Entity(UserConnection, new Guid("09FCE1F8-515C-4296-95CD-8CD93F79A6CF"));
    contryEntity.FetchFromDB("Name", country);
    // Присваивает колонке Name переданное название города.
    entity.SetColumnValue("Name", city);
    // Присваивает колонке CountryId UId переданной страны.
    entity.SetColumnValue("CountryId", contryEntity.GetTypedColumnValue<Guid>("Id"));
    var result = entity.Save();
    return result;
}

© Terrasoft 2002-2020.

Был ли данный материал полезен?

Как можно улучшить эту статью?