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 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.


If the entity is in a hierarchy of type TargetPerEntityHierarchy you don't have to set the discriminator value for the entity type, this is done for you automatically: just create a new instance of the entity type you want to use, and the discriminator value is automatically set and will be saved with the entity.

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.


Fields which get their values from a trigger, from newid() or a default constraint calling a user defined function are not considered sequenced fields and these values will not be read back, so you'll have to supply a value for these fields prior to saving the entity. This isn't true for fields which are of type unique_identifier on SqlServer 2005 when the DQE is set in SqlServer2005/SqlServer2012 compatibility levels and the field has in the database a default value of NEWSEQUENTIALID(). See: Generated code - Database specific features