Creating a new entity instance

To create a new entity instance, you first have to instantiate an empty entity class instance. In our example we'll use the Customer entity and we'll create a new Customer instance.

CustomerEntity customer = new CustomerEntity();

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 class instance 2 the entity data (the entity instance) has to be persisted / saved in the persistent storage. Let's add the customer Foo Inc. to the database:

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_Number = "(604)555-1234";
customer.PostalCode = "90211";
// save it. We require an adapter for this
using(DataAccessAdapter adapter = new DataAccessAdapter())
    adapter.SaveEntity(customer, true);
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_Number = "(604)555-1234"
customer.PostalCode = "90211"
' save it. We require an adapter for this
Using adapter As New DataAccessAdapter()
    adapter.SaveEntity(customer, True)
End Using

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


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.

Refetch and Out of sync behavior.

The code above will save the data directly to the persistent storage (database). The SaveEntity overload used also accepts a boolean for refetch. This boolean, here the value true is specified, controls whether the data of the entity is refetched right after the save action. Adapter requires this so the entity class instance contains the latest data and is 'in-sync'.

If we would have passed false or used the overload SaveEntity(entity), the entity class instance customer would have been marked 'out of sync'. This means that the entity's data has to be refetched from the database prior to reading from one of the entities properties. If you do not require the saved entity for any further processing, you don't need to refetch it and you can save yourself a roundtrip by simply omitting the 'true' in the SaveEntity() call. You can also flag an entity automatically as 'fetched' again. See Entity state control for details.

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 SaveEntity(). The new value for sequenced columns is available to you after SaveEntity(), even though you haven't specified that the entity has to be refetched.

This can be helpful if you want to refetch the entity later. Because the entity saved is new (customer.IsNew is true), SaveEntity() 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