1. Web Client SDK

Entities client

The SDK provides an Entities client to perform CRUD operations on entities.

Note

The client variable in the following code examples refers to the IMClient instance. When using the Web SDK, the variable name can be chosen freely, but it is also called client at instantiation in the documentation.

Get entities

The following method gets an entity by id:

IEntity entity = await MClient.Entities.GetAsync(entityId);

When the entity does not exist or the user does not have enough permissions to read it, the method returns null.

Note

There are many options to load entities by id, by identifier or by definition. For more information about the different options, please refer to the IEntitiesClient in the API reference.

Note

It is possible to pass loading configurations when loading entities. For more information about loading configurations, please refer to the load configurations section.

Create entities

An entity can only be instantiated using the EntityFactory.

In the following snippet, an Asset entity is created locally.

IEntity asset = await MClient.EntityFactory.CreateAsync("M.Asset");
asset.SetPropertyValue("Title", "AssetName");

In the following snippet, the locally created Asset entity is sent to the server to be validated and persisted.

long id = await MClient.Entities.SaveAsync(asset);

The returned ID is the ID of the newly created entity. To get the latest version of this entity, use the ID to get it from the server again.

Copy entities

An entity can be copied by using the CopyAsync method of the entities client.

await MClient.Entities.CopyAsync(entityId, entityCopyOptions);

Entities can be copied by specifying a copy profile or the Properties and Relations you want to overwrite, keep, ignore, remove, and so on.

In the following snippet a new M.Asset entity is created based on an existing M.Asset entity. In the new entity the original entity's Title will be overwritten with a new value, the Description will be ignored, the FileName will be kept as well as the AssetTypeToAsset relation and the LocalizationToAsset will be removed:

var options = new EntityCopyOptionsBuilder()
  .WithProperty("Title", PropertyCopyMethod.Overwrite, "new title")
  .WithProperty("Description", PropertyCopyMethod.Ignore)
  .WithProperty("FileName", PropertyCopyMethod.Keep)
  .WithRelation("AssetTypeToAsset", RelationCopyMethod.Keep)
  .WithRelation("LocalizationToAsset", RelationCopyMethod.Remove)
  .Build();

var copyId = await MClient.Entities.CopyAsync(originalEntityId, options);

The returned ID is the ID of the newly created entity.

In the following snippet an existing M.Asset entity is updated based on another existing M.Asset entity. In the new entity the original entity's Title will be overwritten with a new value, the Description will be ignore, the FileName will be kept as well as the AssetTypeToAsset relation, the LocalizationToAsset will be removed and the AssetMediaToAsset relation will be ignored:

 var options = new EntityCopyOptionsBuilder()
  .WithDestinationEntityId(destinationEntityId)
  .WithProperty("Title", PropertyCopyMethod.Overwrite, "new title")
  .WithProperty("Description", PropertyCopyMethod.Ignore)
  .WithProperty("FileName", PropertyCopyMethod.Keep)
  .WithRelation("AssetTypeToAsset", RelationCopyMethod.Keep)
  .WithRelation("LocalizationToAsset", RelationCopyMethod.Remove)
  .WithRelation("AssetMediaToAsset", RelationCopyMethod.Ignore)
  .Build();

var copyId = await MClient.Entities.CopyAsync(originalEntityId, options);

The returned ID is the same ID as of the destination entity.

In the following snippet a new M.Content entity is created based on an existing M.Content entity. The Properties and Relations that will be copied, ignored, kept, etc. are defined by the out-of-box Drafts copy profile for M.Content entities.

var options = new EntityCopyOptionsBuilder()
  .WithCopyProfile(30102) // ID of the OOB Drafts Copy Profile for M.Content entities
  .Build();

var copyId = await MClient.Entities.CopyAsync(originalEntityId, options);

The returned ID is the ID of the newly created entity.

Update entities

Similar to creating entities, use the SaveAsync method on the entities client after performing the modification.

long id = await MClient.Entities.SaveAsync(asset);

The returned ID is the same ID of the entity. To get the latest version of this entity, use the ID to get it from the server again.

Delete entities

Entity deletion can be achieved by using the DeleteAsync method of the entities client. The entity ID needs to be specified for deletion.

await MClient.Entities.DeleteAsync(entityId);
If you have suggestions for improving this article, let us know!