Creating a new entity instance

This section discusses how to create a new entity and save it to the database and how to modify an existing entity and persist the changes. To create the entity in the persistent storage, two things have to be done: 1) the entity's data (which is new) has to be stored in the new entity object and 2) the entity data has to be persisted / saved in the persistent storage. Let's add the customer Foo Inc. to the database, do the following. First we'll instantiate an empty entity object, in this case a new Customer, and then fill it with data, after which we'll save it with the Save method.

var customer = new CustomerEntity();
customer.CustomerID = "FOO";
customer.Address = "1, Bar drive";
customer.City = "Silicon Valey";
customer.CompanyName = "Foo Inc.";
customer.ContactName = "John Coder";
customer.ContactTitle = "Owner";
customer.Country = "USA";
customer.Fax = "(604)555-1233";
customer.Phone = "(604)555-1234";
customer.PostalCode = "90211";
// save it
customer.Save();

Customer has another field, Region, which isn't given a value. Region can be NULL and will end up as NULL in the database as it has no value in the entity saved.

This will save the data directly to the persistent storage (database). The entity class instance customer itself is marked 'out of sync', which means that the entity's data is refetched from the database when you try to read one of the object's field's value.

This way, you can immediately refetch values which are set inside the database, e.g. default values for columns.

Sequences / Identity value refetch

The code is aware of sequences / identity columns and will automatically set the value for an identity / sequence column after the entity is physically saved inside Save(). The new value for sequenced columns is available to you after Save(), even though you haven't specified that the entity has to be refetched.

Because the entity saved is new (customer.IsNew is true), Save() will use an INSERT query. After a successful save, the IsNew flag is set to false and the State property of the Fields object of the saved entity is set to EntityState.Fetched (if the entity is also refetched) or EntityState.OutOfSync.