CreateService

When you want to create a new entry then you need to use a combination of the CreateSetupService and the CreateService. The CreateSetupService is used to produce class to show the user for them to fill in and, when returned the CreateService will then create it.

It might feel like you do not need the CreateSetupService as you could just new the class yourself. However read on and see that CreateSetupService is sometime useful to pre-load some information. We suggest you use it all the time as taht means you can have a standard template for create and just copy it and change the class it uses.

CreateSetupService (sync and async)

This is used to get a class to show to the user so they can fill in the properties etc to create a new data item. You define what you require by providing of type T, where T is either a data class or a DTO of the right type.

If the item is a DTO then method SetupSecondaryData is called (unless you suppress it - see CrudSalesOrderDetailDto where SetupSecondaryData is not needed). This allows the developer to overide SetupSecondaryData and add any other property setup needed in the Dto. See DetailPostDto for an example of overriding SetupSecondaryData to provide information for dropdown lists to help the user choose the correct author and tags.

The commands are:

• T GetDto<T>() - sync
• Task<T> GetDtoAsync<T>() - async

CreateService/CreateServiceAsync

This service has the methods to create the new data item from the class it is provided. The provided class should be either a class used in the EF database or a DTO which must be inherited from EfGenericDto or EfGenericDtoAsync respectively. This class must contain a property, or properties, that are the primary keys of the class and these keys must already been filled in (see CreateSetupService/CreateSetupServiceAsync above).

If the data T is a DTO then it calls the CopyDtoToData method which only copies over the properties in the DTO that have NOT been marked with the [DoNotCopyBackToDatabase] attribute. This gives the developer the option of excluding updates of certain properties. That is very useful and is not available on the direct access.

Also the developer can override the method CopyDtoToData to incorportate their own processes to set the right values of the properties before calling base.CopyDtoToData (see example in DetailPostDto). The commands are:

• ISuccessOrErrors Create( newData) - sync
• Task<ISuccessOrErrors> CreateAsync( newData) - async

The ISuccessOrErrors class returns a status. If successful the property .IsValid is true and the property SuccessMessage has a confirmation message. If the property .IsValid is false then the List property Errors contains a list of errors. If the status is not valid then the command calls SetupSecondaryData to ensure any secondary properties needed to create the item are set (see CreateSetupServices above on why this is called).

Note: when a new entry is created then the primary key(s) of the created are filled in. If it is a direct create then EF does that. If it is a create via a DTO then the primary key(s) of the main database class, i.e. the database class mentioned in the EfGenericDto/EfGenericDtoAsync definition, are copied back into the DTO. This is useful if you want to hand on the primary key(s) of the newly created entry to another part of the program. (See example NewOrder action in OrdersController. Not that it uses the SalesOrderID of the newly created SalesOderHeader to hand onto the next stage)

One other command exists in the DTO version, called ResetDto( dto). This should be called if there any model errors as, if required, it calls SetupSecondaryData to ensure any secondary properties needed to create the item are set. See beginning of Create action in PostsController The two versions of this command are:

• TDto ResetDto( dto) - sync
• TDto ResetDtoAsync( dto) -async