by Brian Noyes (brian.noyes@solliance.net)
www.solliance.net
Server Side
- BreezeController vs OData vs client enriching
Query Calling Pattern
- Client > executeQuery(query) > Entity Manager > GET Metadata from Controller (first time) > GET Query the controller > Return Query Results
SaveChanges Calling Pattern
- Client > saveChanges > Entity Manager > POST Modified Entity ChangeSet > Controller > Return Server Persisted Entities
RPC, CRUD, REST, ODATA Services
- Breeze routing is action-based (contains an entire model) > by default using a WebActivator.PreApplicationStartMethod(...)
- OData query parameters are turned into an expression tree that is executed against the return IQueryable by the query filter
- SaveChanges takes a JObject bundle with a batch of entities.
Extend EFContextProvider to add custom code
- BeginSaveEntity, BeginSaveEntities (Derived or Delegated)
_ContextProvider.BeforeSaveEntitiesDelegate = BeforeSaveEntities;
private Dictionary<Type, List<EntityInfo>> BeforeSaveEntities(Dictionary<Type, List<EntityInfo> saveMap)
{
var validator = new ProductValidator();
foreach (var type in saveMap.Keys)
{
if (type == typeof(Product))
foreach (var productEntityInfo in saveMap[type])
{
validator.Validate((Product)productEntityInfo.Entity)
}
}
}
Working with OData Services
- On client data.js is needed
- Server needs to define Entity Data Model with same namespace as entity types namespace
- Metadata returned from the server needs to include foreign key relation information
- Need some changes to the way you setup Entity Data Model and return metadata from the server
public class ZzaODataService : DataService<ZzaEntities>
{
public static void InitializeService(DataServiceConfiguration config)
{
config.SetEntitySetAccessRule("Products", EntitySetRights.All);
config.DataServiceBehavior.MaxProtocolVersion = DataServiceProtocolVersion.V3;
}
}
public static void RegisterRoutes(RouteCollection routes)
{
...
routes.IgnoreRoute("{resource}.svc/{*pathInfo}");
...
}
- edmx > properties > Namespace: ZzaODataWeb (same project space as service)
app = {};
breeze.config.initializeAdapterInstance({dataService:"OData"});
em = new breeze.EntityManager("ZzaODataService.svc");
- GET /ZzaODataService.svc/$metadata (returns xml)
- GET /ZzaODataService.svc/Products
- POST /ZzaODataService.svc/$batch (multi-part mime message)
Breeze Query Basics
app.em = new breeze.EntityManager("breeze/Zza");
breeze.EntityQuery.from("Products").where("Description","contains","bacon");
app.em.executeQuery(query).then(...).fail(...);
var p = new breeze.Predicate("Description","contains","bacon");
... .where(p);
var gteMay1 = new breeze.Predicate("OrderDate", "greaterThanOrEqual", moment("2013-05-01");
var lteMay31 = new breeze.Predicate("OrderDate", breeze.FilterQueryOp.LessThanOrEqual, moment("2013-05-31");
...
var predicate = breeze.Predicate.and(gteMay1, lteMay31, gt100);
... orderBy("Name");
... orderBy("TotalPrice, Order.OrderDate");
... orderBy("OrderDate desc").skip(currentPage() * pageSize).take(pageSize);
... orderBy("OrderDate desc").skip(currentPage() * pageSize).take(pageSize).inlineCount();
... select("LastName, Phone, State");
... from("OrderItems").where("Order.Customer.LastName","equals", queryInput()).select("Order.OrderDate, Product.Name, Quantity");
-> use Product_Name, Order_OrderDate to reference the projected elements.
... query.expand("Orders,Orders.OrderDetails,Orders.OrderDetails.Product"); //eagerloading
Breeze Query Advanced
Pre-fetching Metadata is needed when getting by id or creating.
... EntityManager.fetchMetadata().fail(...);
... EntityManager.fetchEntityByKey("Products", key).then(...);
public object Lookups()
{
var products = _ContextProvider.Context.Products.ToList();
...
return { products, productOptions };
}
breeze.EntityQuery.from("Lookups");
... data.results[0].products
... data.results[0].productOptions
public IQueryable<OrderItem> OrderItemsWithCouponCode(string couponCode, string customerClass)
{
...
}
var query = breeze.EntityQuery.from("OrderItemsWithCouponCode").withParameters({ couponCode:"XYZ", customerClass:"Gold"});
Server-Driven Queries (group by, sum, ...)
public IQueryable<object> TopCustomers()
{
var query = (from o in _ContextProvider.Context.Orders
group o by o.CustomerId into g
select new { Customer = g.FirstOrDefault().Customer.LastName, Total = g.Sum(o => o.ItemsTotal) }).OrderByDescending(a => a.Total);
return query;
}
... from("TopCustomers").take(10);
... requeryProducts.push(product)
... fromEntities(requeryProducts); //or by id that replaces the cache, you can also put a sigle entity
breeze.EntityQuery.from("Products").where(...)
... em.executeQueryLocally(query); //synchronous
query.using(breeze.FetchStrategy.FromLocalCache); //async with promise
EntityAspect: contains metadata and state information about the entity
- breeze.NamingConvention.camelCase.setAsDefault(); //type and collections are pascal case, properties or camelcase
EntityManager.createEntity: creates instance and add to cache
newCustomer = function() {
var cust - em.createEntity("Customer", { id: breeze.core.getUuid() });
return cust;
}
EntityType.createEntity: reference from meta, entity from meta, create, add to cache
newCustomer = function() {
var metadataStore = em.metadataStore;
var custType = metadataStore.getEntityType("Customer");
var cust = custType.createEntity({ id: breeze.core.getUuid() });
em.addEntity(cust);
return cust;
}
var pendingStatus = em.executeQueryLocally(breeze.EntityQuery.from("OrderStatuses").where("name", "equals", "Pending"))[0];
order.orderStatusId(pendingStatus.id());
return order;
addToOrder = function(product) {
if (!Order()) order(zzaDataService.createNewOrder(customer()));
var orderItem = order().entityAspect.entityManager.createEntity("OrderItem");
orderItem.order(order());
orderItem.product(product);
orderItem.productSizeId(1);
orderItems.push(orderItem);
}
editingCustomer().entityAspect.rejectChanges();
em.rejectChanges();
//after accepting changes you will not be able to persist them !
... entityAspect.acceptChanges(); //should only be used when mocking data
customer.entityAspect.setDeleted();
customers.remove(customer);
Named Saves
zzaDataService.saveCustomers().fail(...)
...
var customers = em.getChanges("Customer");
return em.saveChanges(customers);
...
var saveOptions = new breeze.SaveOptions({ resourceName:"SaveOrder" });
var orders = [order];
return em.saveChanges(orders, saveOptions);
...
[HttpPost]
public SaveResult SaveOrder(JObject saveBundle)
{
return _ContextProvider.SaveChanges(saveBundle);
}
Working with Entities on the client
Entity States:
- Unchanged - after being loaded by a query or after successful saveChanges
- Modified - previously unchanged entity has a property change
- Added - entity has been created and added to the cache, but not saved to back end
- Deleted - previously unchanged entity is marked for deletion
- Detached
Newly created entity that has not been added to the cache
Added entity that gets marked for deletion
Deleted entity after saveChanges is complete
Entities that were in the cache when EntityManager.clear is called
EntityManager.detachEntity called
EntityAspect.entityState
createEntity, setDeleted, rejectChanges, acceptChanges
EntityAspect.setModified, EntityAspect.setUnchanged
Extending Entities: Modify the EntityType in the Breeze metadataStore
Saved when exported, but not persisted to the server.
addEntityExtensions = function () {
var store = em.metadataStore;
store.registerEntityTypeCtor("Customer", Customer)
}
var Customer = function() {
this.firstName = ko.observable(''); //solves race condition
this.lastName = ko.observable('');
this.fullName = ko.computed(function() {
return this.firstName() + " " + this.lastName();
}, this);
}
OR
Customer.prototype.getFullName = function() {
return this.firstName() + " " + this.lastName();
}
Handling Entity Property Changes
- Breeze raises its own (observable agnostic) property change events
- EntityAspect.propertyChanged.subscribe returns a subscription token
- Avoid memory leaks by EntityAspect.propertyChanged.unsubscribe(token)
tokens = {};
var token = addingCustomer().entityAspect.propertyChanged.subscribe(function()arg {
logger.info("Customer:" + arg.entity.fullName() + "property " + arg.propertyName + "changed value" + arg.oldValue + "into" + arg.newValue);
})
tokens[addingCustomer().id] = token;
... unsubscribe(tokens[customers()[i].id]) ...
EntityManager.entityChanged.subscribe (eg. undo)
-> entityAction, entity, args
Exporting and importing cached entities
Using an entityChangedHandler to make sure changes are saved locally for when user would close browser before saving
var bundle = em.exportEntities(em.getChanges());
window.localStorage.setItem("magickey", bundle);
...
var bundle = window.localStorage.getItem("magickey");
if (bundle) em.importEntities(bundle);
...
clear local storage on save
Validation
- Returns HTTP 403 Forbidden status code when validation errors
- Collection of ValidationError objects per entity (propertyName, property, errorMessage, context, isServerError, key, validator)
- Automatically adds type, required and length validation
- Configurable - EntityManager.validationProperties
saveError = function (error) {
if (error.entityErrors) {
showValidationErrors(error.entityErrors);
}
else {
logger.error(error.message, "Error saving data");
}
}
showValidationErrors = function (errors) {
var errorMessage = "";
errors.map(function (e) {
if (errorMessage.length > 0) errorMessage += ", ";
errorMessage += e.errorMessage;
});
logger.error(errorMessage, "Validation Errors");
}
Data Annotations (System.ComponentModel.DataAnnotations)
[Required], [StringLength(50)], Range, RegularExpresssion, Compare
[DataType(DataType.Currency)], Date, Time, DateTime, PostalCode, ...
Phone, [EmailAddress], CreditCard, Url
function initValidation(em) {
var store = em.metadataStore;
var userType = store.getEntityType("User");
var phoneProp = userType.getProperty("phone");
phoneProp.validators.push(breeze.Validator.phone());
}
var userKeyValidator = breeze.Validator.makeRegExpValidator(
"userKeyVal",
/^[A-Z] ... regex ... $/,
"%displayName% '%value%' is not a valid GUID");
);
if (validateUser(editingUser()) { ... saveChanges ... }
validateUser = function(user) {
if (!user.entityAspect.validateEnitity()) {
var errors = user.entityAspect.getValidationErrors();
showValidationErrors(errors);
return false;
}
return true;
}
function isValidScoreRange(value, context) {
return value > context.minValue && value <= context.maxValue;
}
var scoreRangeValidator = new breeze.Validator("scoreRangeValidator", isValidScoreRange, { messageTemplate: '...' });
userType.getProperty("score").validators.push(scoreRangeValidator);
function rangeValidatorFactory(context) {
return new breeze.Validator("rangeValidator", isValidRange,
{
minValue: context.minValue,
maxValue: context.maxValue,
messageTemplate: '... %minValue% ... %maxValue% ...'
OR messageTemplate: breeze.core.formatString("'... %1 ... %2'", context.minValue, context.maxValue)
}
);
}
userType.getProperty("score").validators.push(rangeValidatorFactory({ minValue:1, maxValue:100 }));
//register to allow export and imports
breeze.Validator.register(userKeyValidator);
breeze.validator.registerFactory(rangeValidatorFactory, "rangeValidator");
app.em.validationErrorChanged.subscribe(function(args) {
if (args.added) ...
}
editSubscriptionToken = editingUser().entityAspect.validationErrorsChanged.subscribe(...);
... unsubscribe ...
Customer Server Validation
- Inherit from ValidationAttribute
- CustomValidatorAttribute
- Custom business logic (EntityErrorsException from BreezeController BeginSaveEntity)
- [CustomValidation(typeof(UserValidationRules), "ValidateEmail")]
public static class UserValidationRules
{
public static ValidationResult ValidateEmail(string value, ValidationContext context)
{
if (!value.EndsWith("...") return new ValidationResult("...");
return ValidationResult.Success;
}
}
private bool BeforeSaveEntity(EntityInfo entityInfo)
{
User user = entityInfo.Entity as User;
if (user != null)
{
if (!user.CreditCard.StartsWith("5"))
{
throw new EntityErrorsException(new List<EntityErrors>)
{
new EntityError
{
EntityTypeName = user.GetType().ToString(),
ErrorMessage = "We only accept Mastercard",
PropertyName = "CreditCard",
ErrorName = "CreditCardValidationError",
KeyValues = new object[] { user.Id }
}
}
}
}
return true;
}