Fork me on GitHub
2sxc 9.0 for DNN 7 to 9
Website Builder, Content Manager, App-System: free and amazing - done your way
You are here: Home  >  Docs  >  Feature

Create/Update/Delete Entities in Razor/C#

Introduced in Version 06.05
Demos of this feature

The Entity-Manipulation API

To enable programmers to create / edit / delete entities using their own C# code, we provide a simplified API for just these actions. So you have 3 commands, as follows:

  1. Create
  2. Update
  3. Delete

How can you quickly learn this?

Install these tutorial apps, discover!

Where can you use this?

Basically there are 2 typical places for this

  • In your C# Razor template (see related posts below)
  • In your C# WebAPI Controller (see related posts below)

 

The Syntax

These commands are attached to a DataController - who is in charge of data-management. So the most common way to use it is

  • App.Data.Create(Content-Type-Name, DictionaryOfValuesToAdd)
    • or App.Data.Create(Content-Type-Name, DictionaryOfValuesToAdd, UserNameToLog)
  • App.Data.Update(Id-As-Int, DictionaryOfValuesToChange)
    • or App.Data.Update(Id-As-Int, DictionaryOfValuesToChange, UserNameToLog)
  • App.Data.Delete(Id-As-Int)
    • or App.Data.Delete(Id-As-Int, UserNameToLog)

 

Catching Errors

All these commands will either succeed or throw an error, so you will usually do something like

try

{

    App.Data.Create("Comment", values);

    message = App.Resources.SaveSucceeded;

}

catch

{

   message = App.Resources.SaveFailed;

}

 

The Values-Dictionary

This is a simple Dictionary<string, object>. Note that if you use invalid types, the save will fail. Here's an example

var Values = new Dictionary<string, object>;

Values.Add("Title", Request.Form["Title"]);

Values.Add("Message", Request.Form["Message"]);

Values.Add("Rating", Convert.ToInt(Request.Form["Rating"]);

DataController().Add("Comment", Values);

 

Setting Published State

In 2sxc each save-operation can be published or unpublished. If it's unpublished, then users with read-access will see the previous state (so either without a just-added-entity, or in the previously published version). By default, the simple API will have the following effect on data:

  • When you Create new entities, these are published by default
  • When you Update existing entities, these will NOT change the published state by default. So updating an entity which has a draft will only affect the draft (by default)
  • Delete is always a full delete, removing both a draft and/or the published entity

 

You can specifically say what you want as follows:

Values.Add("IsPublished", true); // would make it published

Values.Add("IsPublished", false); // keep it unpublished

 

Just so you don't get things wrong: an Update with "IsPublished"=false will not hide the existing entity, but will hide the change you just made. You can discover more in the related posts.

 

Some Performance Notes

2sxc is fully cached - at the App-Level. So any changes will reload the cache for this App. This will usually not affect your work, but could have 1-2 side effects

  1. if your App had many thousand entities, you may feel that the read after a write may have a delay
  2. If you have entities in some object before saving, these entities may become invalid after saving - so they might still contain the deleted entity as it was cached before the change.

Read more about the cache in the related posts below.

 

Relationships to other Entities

Relationships are established through EntityIds (or GUIDs?) todo. Note that the sort-order is preserved (todo: check). To add them, use code as follows:

Values.Add("Format", new List<int>() { formatId }); // add one

var tags = new List<int>();

tags.Add(17);

tags.Add(32);

Values.Add("Tags", tags);

 

Notes on Multiple Languages

The simple API assumes standard language needs - so it will always only create entities in the main language, update attributes in the main language and of course delete the entire entity in all languages. For language-specific data handling (which can be very complex) there is currently no official API.

 

Some Security Notes

For security reasons, the simple API does the following

  1. Only allow changes in the current portal and App

 

Deleting Entities

This will fail if the entity is in use. Common In-Use-Cases are:

  1. when the entity has incoming relationships (so a person-entity, who is referred to in a books author-field)
  2. when the entity is in use on a specific module (in use means that it was assigned manually in "content-mode")
  3. when the entity is used as a demo-entity in a view/template

 

The error message should help you get it right.

 

 

Tags for this feature

2serve . 2invent . 2create is 2be.