The DomainService

The DomainService we’re testing looks like this.

  public class BookClubDomainService : RepositoryDomainService
  {
    public BookClubDomainService(
      IUnitOfWork unitOfWork,
      IBookRepository bookRepository,
      ILibraryService libraryService,
      IApprovalSystem approvalSystem) { ... }

    // Test 1: Operation should return all books
    // Test 2: Operation should return books with categories
    // Test 3: Operation should return books ordered by BookID
    public IQueryable<Book> GetBooks() { ... }

    // Test 1: Operation should return all books for category
    // Test 2: Operation should return books ordered by BookID
    public IQueryable<Book> GetBooksForCategory(int categoryId) { ... }

    // Test 1: Operation should insert book
    // Test 2: Operation should set the added date
    // Test 3: Operation should request approval for book with invalid ASINs
    // Test 4: Operation should request approval for book not yet published
    public void InsertBook(Book book) { ... }

    // Test 1: Operation should update book
    // Test 2: Operation should return validation errors
    public void UpdateBook(Book book) { ... }

    // Test 1: Operation should update book
    // Test 2: Operation should update the added date
    [Update(UsingCustomMethod = true)]
    public void AddNewEdition(Book book) { ... }

    // Test 1: Operation should delete book
    // Test 2: Operation should require authentication
    [RequiresAuthentication]
    public void DeleteBook(Book book) { ... }

    // Test 1: Operation should return the most recent added date
    public DateTime GetLatestActivity() { ... }
  }

It has the standard Query, Insert, Update, and Delete operations in addition to custom Query, Update, and Invoke(/Service) operations. The constructor accepts a number of parameters; each representing an external dependency in the code. I’ve labeled each method with the tests that we’ll write against it so we don’t have to know the details of the implementation (they’re in the sample, I’m just skipping them in the post).

The DomainServiceTestHost

The DomainServiceTestHost is a new class in the Microsoft.ServiceModel.DomainServices.Server.UnitTesting assembly (now on NuGet and soon to be shipping with the Toolkit). It’s designed to help you test individual DomainService operations. The API falls closely in-line with DomainService conventions (and may help clarify them if you’re still a little hazy). For instance, the test host has a Query method for retrieving data, and Insert, Update, and Delete methods for modifying it.

In addition to standard operation support, the test host makes it simple to test validation and authorization. For each standard signature in the DomainServiceTestHost, there is a TryXx variant that makes it easy to capture validation errors. For instance, Query is paired with TryQuery and Insert with TryInsert. Also, each time you create a test host, you can pass an  IPrincipal into the constructor that the operations should be run with. This makes it easy to cycle through a number of test users as you validate your authorization metadata. Finally, the test host can be created with a factory method that it uses to instantiate a DomainService. This allows you to initialize a DomainService with test-specific dependencies.

Testing a DomainService

Finally we’re getting to the good part. In this section, I’ll walk you through the steps necessary to unit test your business logic. First, we’ll initialize the local variables we’ll use with each test.

  [TestInitialize]
  public void TestInitialize()
  {
    this._libraryService = new MockLibraryService();
    this._approvalSystem = new FakeApprovalSystem();
    this._unitOfWork = new FakeUnitOfWork();
    this._bookRepository = new MockBookRepository();

    this._domainServiceTestHost =
      new DomainServiceTestHost<BookClubDomainService>(
        this.CreateDomainService);
  }

  private BookClubDomainService CreateDomainService()
  {
    return new BookClubDomainService(
             this._unitOfWork,
             this._bookRepository,
             this._libraryService,
             this._approvalSystem);
  }

As you can see, I’ve written simple mock/fake/stub types for each dependency. I discussed the MockBookRepository a little in my previous post. For the context of the following tests, it’s important to point out that I’ve initialized the repository with an initial set of data. The other three are just simple test implementations. Also, I’ve provided a CreateDomainService method that I can pass to the test host that initializes my BookClubDomainService with the test dependencies. If you’re not familiar with the Visual Studio testing, the [TestInitialize] method will get called before the start of each test.

Starting with something simple, we’ll take a look at the test for the default query.

  [TestMethod]
  [Description("Tests that the GetBooks query returns all the books")]
  public void GetBooks_ReturnsAllBooks()
  {
    IEnumerable<Book> books = this._domainServiceTestHost.
                                Query(ds => ds.GetBooks());

    Assert.AreEqual(
      this._bookRepository.GetBooksWithCategories().Count(), books.Count(),
      "Operation should return all books");
  }

In this method, we’re asking the test host to return the results of the query. The ‘ds’ parameter in the lambda is the instance of the DomainService we’re testing. Since the IntelliSense for the query operation is a little verbose (as is anything where the Expression type shows up), I’ll give you another sample so you get the hang of it. This time we’re testing the custom query.

  [TestMethod]
  [Description(
     "Tests that the GetBooksForCategory query orders books by BookID")]
  public void GetBooksForCategory_OrderedByBookID()
  {
    int categoryId = this._bookRepository.GetTable<Category>().
                       First().CategoryID;

    IEnumerable<Book> books = this._domainServiceTestHost.Query(
                                ds => ds.GetBooksForCategory(categoryId));

    Assert.IsTrue(books.OrderBy(b => b.BookID).SequenceEqual(books),
      "Operation should return books ordered by BookID");
  }

In this snippet we’re passing a local variable to the query operation, but everything else is pretty much the same. We’ve gotten the returned collection and now we’re verifying that it is in sorted order.

Tests for Insert, Update, and Delete operations are just as easy to write. Just calling the method on the host will redirect to the corresponding operation in your DomainService.

  [TestMethod]
  [Description("Tests that the InsertBook operation inserts a new book")]
  public void InsertBook_InsertsNewBook()
  {
    int categoryId = this._bookRepository.GetTable<Category>().
                       First().CategoryID;

    Book book = new Book
    {
      ASIN = "1234567890",
      Author = "Author",
      CategoryID = categoryId,
      Description = "Description",
      PublishDate = DateTime.UtcNow.Subtract(TimeSpan.FromDays(1)),
      Title = "Title",
    };

    this._domainServiceTestHost.Insert(book);

    Assert.IsTrue(book.BookID > 0,
      "New book should have a valid BookID");

    Book addedBook = this._bookRepository.GetEntities().
                       Single(b => b.BookID == book.BookID);

    Assert.IsNotNull(addedBook,
      "Operation should insert book");
  }

To rephrase what I said above, calling Insert on the test host with a Book calls into our DomainService operation, InsertBook. As you can see, at the end of this test our new book has been added to the repository.

In addition to Query, Insert, Update, and Delete methods, Named Updates and Invoke operations are also supported. In both cases, the syntax is very similar to testing a Query.

  this._domainServiceTestHost.Update(
    ds => ds.AddNewEdition(book), original);

  DateTime result = this._domainServiceTestHost.Invoke(
    ds => ds.GetLatestActivity());

AddNewEdition updates the book and runs custom business logic and GetLatestActivity returns a DateTime related to the newest book. Again, the ‘ds’ parameter in the lambda expression refers to the DomainService being tested.

Testing Validation and Authorization

Testing validation and authorization metadata for a DomainService operation can be just as important as testing the business logic. A unit test suite verifying authorization and validation would be a great tool to prevent service security regressions.

Validation is fairly straightforward to test. Instead of using the test host methods I’ve already described, you should use their TryXx variants.

  [TestMethod]
  [Description("Tests that the UpdateBook operation returns 
     validation errors when passed an invalid book")]
  public void UpdateBook_SetsValidationErrors()
  {
    Book original = this._bookRepository.GetEntities().First();
    Book book = new Book
    {
      AddedDate = original.AddedDate,
      ASIN = "Invalid!",
      Author = original.Author,
      BookID = original.BookID,
      Category = original.Category,
      CategoryID = original.CategoryID,
      Description = original.Description,
      PublishDate = original.PublishDate,
      Title = original.Title,
    };

    IList<ValidationResult> validationErrors;
    bool success = this._domainServiceTestHost.TryUpdate(
                     book, original, out validationErrors);

    Assert.IsFalse(success,
      "Operation should have validation errors");
    Assert.AreEqual(1, validationErrors.Count,
      "Operation should return validation errors");
    Assert.IsTrue(validationErrors[0].MemberNames.Single() == "ASIN",
      "Operation should return a validation error for 'ASIN'");
  }

This test calls into UpdateBook with invalid data and then verifies the resulting validation errors are ones we expect.

Authorization tests follow a different approach. Instead of using a different test host method, they set a custom principal that will be used when calling the DomainService operation. While the test host defaults to an anonymous user, an alternate constructor allows you to specify the user that is interesting for your test case.

  this._domainServiceTestHost = 
    new DomainServiceTestHost<BookClubDomainService>(
      this.CreateDomainService,
      BookClubDomainServiceTest.authenticatedUser);

Conclusion

To sum it all up, the DomainServiceTestHost in combination with an IDomainServiceFactory and the Repository pattern makes it simple to unit test your DomainServices in an isolated and reliable fashion. Also, since the test host is just a .NET type, it should be compatible with any and all test tools and frameworks you feel like using it with. Hopefully this series gave you a good overview of DomainService unit testing. If you have any questions or feature requests, please send them my way. Thanks.

[A Note on the DomainServiceTestHost]

As of the initial release of this test host, there may still be a few edge cases for association and composition change sets that are not supported. If you find any, please let me know so I can put together a scenario for a subsequent release.

Unit Testing Series

• Part 1: The IDomainServiceFactory
• Part 2: The Repository Pattern
• Part 3: The DomainServiceTestHost
• Unit Testing Sample Source
• NuGet: RIAServices.UnitTesting

The pattern I’m using to factor out external dependencies is called the Repository Pattern. It’s well-known and comes in many variations. The variation I’ve chosen here is one that fits quite well with the way RIA consumes and Entity Framework ObjectContext. If you’re using a different data-access technology, feel free to modify this pattern until you get something that works for your scenario.

A Repository Sample

Before I jump into the Repository API or the DomainService setup, I’d like to show what introducing a repository might do to standard DomainService operations. Here are a few operations written directly against an ObjectContext.

  // Test 1: Operation should return all books
  // Test 2: Operation should return books with categories
  // Test 3: Operation should return books ordered by BookID
  public IQueryable<Book> GetBooks()
  {
    return this.ObjectContext.Books.Include("Category").
             OrderBy(b => b.BookID);
  }

  // Test 1: Operation should return all books for category
  // Test 2: Operation should return books ordered by BookID
  public IQueryable<Book> GetBooksForCategory(int categoryId)
  {
    return this.ObjectContext.Books.
             Where(b => b.CategoryID == categoryId).OrderBy(b => b.BookID);
  }

  // Test 1: Operation should update book
  // Test 2: Operation should return validation errors
  public void UpdateBook(Book book)
  {
    this.ObjectContext.Books.AttachAsModified(
      book, this.ChangeSet.GetOriginal(book));
  }

Upon introducing a repository into this code, the operations will be slightly different.

  // Test 1: Operation should return all books
  // Test 2: Operation should return books with categories
  // Test 3: Operation should return books ordered by BookID
  public IQueryable<Book> GetBooks()
  {
    return this._bookRepository.GetBooksWithCategories().
             OrderBy(b => b.BookID);
  }

  // Test 1: Operation should return all books for category
  // Test 2: Operation should return books ordered by BookID
  public IQueryable<Book> GetBooksForCategory(int categoryId)
  {
    return this._bookRepository.GetEntities().
             Where(b => b.CategoryID == categoryId).OrderBy(b => b.BookID);
  }

  // Test 1: Operation should update book
  // Test 2: Operation should return validation errors
  public void UpdateBook(Book book)
  {
    this._bookRepository.Update(
      book, this.ChangeSet.GetOriginal(book));
  }

By-and-large we’ve preserved the existing implementation. However, you can now see we don’t have a direct dependency on ObjectContext. Instead all interaction is funneled through the book repository. Doing this will allow us to introduce a mock repository implementation at test time which will allow us to test without any dependency on a database.

The Repository API

I’m going to abbreviate the API I show in this post. There are more interesting types and methods in the sample but I want to keep the conversation here focused. The first type we should look at is the IRepository<T> interface.

  public interface IRepository<T> : IRepository
  {
    IQueryable<T> GetEntities();
    void Insert(T entity);
    void Update(T entity, T original);
    void Delete(T entity);
  }

A repository is a simple type that surfaces methods for the Query, Insert, Update, and Delete operations that commonly show up in DomainServices. Also, the repository interface has a per-type affinity. Specifically, you’d have a separate instance for each root entity type (as a side note, this felt a little verbose to me, but also worked nicely. I’ll let you make the final call as to whether it’s worth the extra typing).

Here’s a partial Repository implementation using Entity Framework.

  public class Repository<T> : IRepository<T> where T : EntityObject
  {
    public virtual IQueryable<T> GetEntities()
    {
      return this.ObjectSet;
    }

    public virtual void Insert(T entity)
    {
      if (entity.EntityState != EntityState.Detached)
      {
        this.ObjectContext.ObjectStateManager.
          ChangeObjectState(entity, EntityState.Added);
      }
      else
      {
          this.ObjectSet.AddObject(entity);
      }
    }
  }

As you can see, the repository contains the familiar code required to work against the EF ObjectContext and ObjectSet.

The next class to look at is a derived repository interface. As you may have noticed already, our book repository has a GetBooksWithCategories method that isn’t in the base interface.

  public interface IBookRepository : IRepository<Book>
  {
    IQueryable<Book> GetBooksWithCategories();
  }

The concrete implementation of this method will show us why it’s interesting.

  public class BookRepository : Repository<Book>, IBookRepository
  {
    public BookRepository(BookClubEntities objectContext)
        : base(objectContext)
    {
    }

    public IQueryable<Book> GetBooksWithCategories()
    {
        return this.ObjectSet.Include("Category");
    }
  }

Specifically, we’ve used the Include method on ObjectSet. Since the include method is specific to entity framework, I’ve placed it behind the repository interface.

The UnitOfWork API

Both DomainServices and Repositories work on the principal that you can make a lot of changes and then submit them all as a single unit-of-work. To facilitate this, our Repository pattern also provides an IUnitOfWork interface.

  public interface IUnitOfWork
  {
    void Save();
  }

Simple. Now we just need to make sure it is called when our DomainService is ready to persist changes. Luckily, the DomainService base class provides a virtual protected method to allow us to do just that.

  // Test 1: Unit of work should be saved
  protected override bool PersistChangeSet()
  {
    this.UnitOfWork.Save();
    return true;
  }

Finally, we need to make sure the unit-of-work can be used to persist the changes to our Entity Framework model. To do this, we can use a partial class to implement the interface on BookClubEntities.

  public partial class BookClubEntities : IUnitOfWork
  {
    public void Save()
    {
      this.SaveChanges();
    }
  }

Now we’ll need to take a look at how all these pieces are wired up.

A DomainService Using a Repository

Like I showed in my previous post, we’ll need to pass the repository to the DomainService’s constructor.

  public BookClubDomainService(
    IUnitOfWork unitOfWork,
    IBookRepository bookRepository,
    ILibraryService libraryService,
    IApprovalSystem approvalSystem)
    : base(unitOfWork, bookRepository) 
  {
    if (bookRepository == null)
    {
      throw new ArgumentNullException("bookRepository");
    }
    if (libraryService == null)
    {
      throw new ArgumentNullException("libraryService");
    }
    if (approvalSystem == null)
    {
      throw new ArgumentNullException("approvalSystem");
    }

    this._bookRepository = bookRepository;
    this._libraryService = libraryService;
    this._approvalSystem = approvalSystem;
  }

You can refer back to my previous post on how to create and bootstrap an IDomainServiceFactory. I won’t repeat the information here, but I’ll give you a quick look at the factory code that creates the DomainService.

  public class BookClubDomainServiceFactory : IDomainServiceFactory
  {
    public DomainService CreateDomainService(
      Type domainServiceType, DomainServiceContext context)
    {
      DomainService domainService;
      if (typeof(BookClubDomainService) == domainServiceType)
      {
        BookClubEntities bookClubEntities = new BookClubEntities();
        domainService = new BookClubDomainService(
          bookClubEntities,
          new BookRepository(bookClubEntities), 
          new LibraryService(),
          new ApprovalSystem());
      }
      else
      {
        domainService = (DomainService)
          Activator.CreateInstance(domainServiceType);
      }

      domainService.Initialize(context);
      return domainService;
    }
  }

Finally, we need to set the BookClubDomainService  to provide the correct metadata about the types it supports. Since we’re returning Entity Framework types, we’ll need to use the LinqToEntitiesDomainServiceDescriptionProviderAttribute.

  [LinqToEntitiesDomainServiceDescriptionProvider(
     typeof(BookClubEntities))]
  public class BookClubDomainService : RepositoryDomainService { ... }

Also, you’ll notice I’ve created a RepositoryDomainService base class to encapsulate some of the common Repository concerns. With all these pieces together, it becomes a simple matter to write DomainService operations.

  // Test 1: Operation should return all books
  // Test 2: Operation should return books with categories
  // Test 3: Operation should return books ordered by BookID
  public IQueryable<Book> GetBooks()
  {
    return this._bookRepository.GetBooksWithCategories().
             OrderBy(b => b.BookID);
  }

Testing With a Repository

Though I plan to save most of this for the next post, it’s worth looking at the MockRespository we’ll use for testing.

  public class MockRepository<T> : IRepository<T>
  {
    private readonly Dictionary<Type, IList> _entities =
      new Dictionary<Type, IList>();

    public List<TEntity> GetTable<TEntity>() { ... }

    public virtual IQueryable<T> GetEntities()
    {
      return this.GetTable<T>().AsQueryable();
    }

    public virtual void Insert(T entity)
    {
      this.GetTable<T>().Add(entity);
    }
  }

The mock repository allows us to populate our table with default data before a test and check the updated contents of the table after the test.

  private class MockBookRepository : MockRepository<Book>, IBookRepository
  {
    public MockBookRepository()
    {
      this.GetTable<Book>().AddRange(new []
      {
        new Book
        {
          AddedDate = DateTime.UtcNow,
          ASIN = "1234567890",
          Author = "Author",
          BookID = 1,
          ...
        },
        ...
      });
    }
  }

Now, when we create our DomainService in our tests, we can pass an instance of MockBookRepository in instead of our real implementation. Using a repository like this in our tests improves the isolation and consistency. In the last post in this series on testing, I will finally show how to write unit tests for your DomainServices.

Unit Testing Series

• Part 1: The IDomainServiceFactory
• Part 2: The Repository Pattern
• Part 3: The DomainServiceTestHost
• Unit Testing Sample Source
• NuGet: RIAServices.UnitTesting

The first step to making your DomainService testable is to identify the external dependencies.

A DomainService with Dependencies

We’ll start by looking at a service that has both business logic and dependencies. I’ve authored it in a pretty straightforward manner so I can highlight specific changes that will improve testability.

  public class BookClubDomainService :
    LinqToEntitiesDomainService<BookClubEntities>
  {
    private readonly LibraryService _libraryService = new LibraryService();
    private readonly ApprovalSystem _approvalSystem = new ApprovalSystem();

    // Test 1: Operation should return all books
    // Test 2: Operation should return books with categories
    // Test 3: Operation should return books ordered by BookID
    public IQueryable<Book> GetBooks()
    {
      return this.ObjectContext.Books.Include("Category").
               OrderBy(b => b.BookID);
    }

    // Test 1: Operation should insert book
    // Test 2: Operation should set the added date
    // Test 3: Operation should request approval for book with invalid ASINs
    // Test 4: Operation should request approval for book not yet published
    public void InsertBook(Book book)
    {
      if ((book.EntityState != EntityState.Detached))
      {
        this.ObjectContext.ObjectStateManager.
          ChangeObjectState(book, EntityState.Added);
      }
      else
      {
        this.ObjectContext.Books.AddObject(book);
      }

      book.AddedDate = DateTime.UtcNow;

      if (!this._libraryService.IsAsinValid(book.ASIN))
      {
        this._approvalSystem.
          RequestApproval(book.Author, book.Title, book.PublishDate);
      }
      else if (book.PublishDate > book.AddedDate)
      {
        this._approvalSystem.RequestApproval(book.ASIN);
      }
    }
  }

A quick look at this service should reveal three concrete dependencies. First, we’re using an Entity Framework ObjectContext to talk to a database. We also have a dependency on an external service, LibraryService, and an internal subsystem, ApprovalSystem. The ObjectContext is a unique case which I’ll tackle in the next post, so for now let’s look at what we can do with the LibraryService and ApprovalSystem.

There are a few options available for testing code with external dependencies. The first is to actually test against the real components; perhaps with modified connection strings to test instances. For example, you could run your tests against a test instance of the database. The second is to use a mocking framework to provide mock implementations for the methods you are using. For example, you could write a quick implementation of LibraryService.IsAsinValid to use only with your tests. I’ve been using Moles recently, but there are many good frameworks available. Finally, you can use a pattern called Dependency Injection to allow your service code to be passed references to external dependencies.

The rest of this post will cover how to use the IDomainServiceFactory interface to enable Dependency Injection. There’s plenty to be said about the other testing options I listed above, but I won’t do it here. A little research should be able to help you determine if and when either of the other options is right for you.

Factoring External Dependencies

Now that we’ve identified our external dependencies, we can change the design slightly to allow them to be pass in to the DomainService. Instead of using the concrete types, LibraryService and ApprovalSystem, we’ll replace them with interfaces.

  public interface ILibraryService
  {
    bool IsAsinValid(string asin);
  }

  public interface IApprovalSystem
  {
    void RequestApproval(string author, string title, DateTime publishDate);
    void RequestApproval(string asin);
  }

Next, we’ll update the DomianService to use these interfaces. More importantly, we’ll update the service to require these dependencies be provided to the constructor.

  public class BookClubDomainService :
    LinqToEntitiesDomainService<BookClubEntities>
  {
    private readonly ILibraryService _libraryService;
    private readonly IApprovalSystem _approvalSystem;

    public BookClubDomainService(
      ILibraryService libraryService, IApprovalSystem approvalSystem)
    {
      if (libraryService == null)
      {
        throw new ArgumentNullException("libraryService");
      }
      if (approvalSystem == null)
      {
        throw new ArgumentNullException("approvalSystem");
      }

      this._libraryService = libraryService;
      this._approvalSystem = approvalSystem;
    }

    // Test 1: Operation should return all books
    // Test 2: Operation should return books with categories
    // Test 3: Operation should return books ordered by BookID
    public IQueryable<Book> GetBooks()
    {
      return this.ObjectContext.Books.Include("Category").
               OrderBy(b => b.BookID);
    }

    // Test 1: Operation should insert book
    // Test 2: Operation should set the added date
    // Test 3: Operation should request approval for book with invalid ASINs
    // Test 4: Operation should request approval for book not yet published
    public void InsertBook(Book book)
    {
      if ((book.EntityState != EntityState.Detached))
      {
        this.ObjectContext.ObjectStateManager.
          ChangeObjectState(book, EntityState.Added);
      }
      else
      {
        this.ObjectContext.Books.AddObject(book);
      }

      book.AddedDate = DateTime.UtcNow;

      if (!this._libraryService.IsAsinValid(book.ASIN))
      {
        this._approvalSystem.
          RequestApproval(book.Author, book.Title, book.PublishDate);
      }
      else if (book.PublishDate > book.AddedDate)
      {
        this._approvalSystem.RequestApproval(book.ASIN);
      }
    }
  }

If you tried to run this service now, you’d see it failing with an error along the lines of “No default constructor exists for the type BookClubDomainService”. To fix this error, we’ll need to understand a little more about how DomainServices are instantiated.

IDomainServiceFactory

Each time a client calls into the DomainService endpoint, the RIA hosting layer uses the singleton DomainService.Factory to create a new instance of the requested DomainService type. The default IDomainServiceFactory implementation expects a DomainService type to provide a parameter-less constructor. Since we’ve changed the constructor above to require two parameters, we now have to create a factory type that can handle our DomainService.

Factories are pretty straightforward to write and only expose a pair of Create/Release methods.

  public class BookClubDomainServiceFactory : IDomainServiceFactory
  {
    public DomainService CreateDomainService(
      Type domainServiceType, DomainServiceContext context)
    {
      DomainService domainService;
      if (typeof(BookClubDomainService) == domainServiceType)
      {
        domainService = new BookClubDomainService(
          new LibraryService(), new ApprovalSystem());
      }
      else
      {
        domainService = (DomainService)
          Activator.CreateInstance(domainServiceType);
      }

      domainService.Initialize(context);
      return domainService;
    }

    public void ReleaseDomainService(DomainService domainService)
    {
      domainService.Dispose();
    }
  }

Now that we have a custom factory, we’ll have to make sure it gets used to instantiate our DomainService. The easiest way to do this is to add a Global.asax file to our web site and bootstrap the factory there.

  public class Global : System.Web.HttpApplication
  {
    protected void Application_Start(object sender, EventArgs e)
    {
      DomainService.Factory = new BookClubDomainServiceFactory();
    }
  }

Now we can run our service successfully again. The update we made to the DomainService will allow us to pass in test-specific implementations of the external dependencies. This in-turn improves the isolation and consistency of our tests. In parts two and three, I will show how to treat your data access layer as an external dependency and how to actually write the tests.

[A Note on Dependency Injection]

Often Dependency Injection is done in a more generic fashion using Injection frameworks. If you find yourself creating a big switch in IDomainServiceFactory.CreateDomainService for each DomainService type in your custom factory, you may find it more maintainable to use a framework. There are plenty of them out there, so it shouldn’t be too hard to find one that works for you.

[An Alternate Design]

Now that you’ve patiently waded through this entire post, it’s worth noting that a custom IDomainServiceFactory is not strictly required to make your DomainService testable. For instance, you could provide two constructors for each DomainService; the parameterized constructor for testing and a default constructor that chooses a default value for each dependency. There are benefits to the factory approach (like Dependency Injection), but I’ll leave it up to you to pick the one that fits best.

Unit Testing Series

• Part 1: The IDomainServiceFactory
• Part 2: The Repository Pattern
• Part 3: The DomainServiceTestHost
• Unit Testing Sample Source
• NuGet: RIAServices.UnitTesting

Links

Since the CTP is large and encompasses a number of different technologies, I thought it’d be worth drawing your attention to RIA-specific links.

Here’s an overview of RIA in AppFabric Applications

Here’s an overview of the Silverlight Business Application Pattern for AppFabric

You can download the AppFabric Samples for the June CTP here

Also, when you download the CTP, make sure you install the AppFabricVsToolsCtp.

Take a Look

I thought about adding some snapshots to this post, but all the RIA stuff is just the same as you’re used to. The goal was to make it easy for you to pick up the CTP and play around with the bits. So take a look and send me some feedback. Let me know how it handles and the kinds of things you want to see. Thanks.

The Loader as part of your View Model

Out of the three parts of the DomainCollectionView (DCV) triad, the loader is the piece mostly closely aligned with your View Model. In fact, I wrote the default implementation (the DomainCollectionViewLoader) with callbacks so you could put all the code you cared about directly in your VM. That said, feel free to blur the lines between your VM and your CollectionViewLoader until you find the balance of functionality and reusability you feel comfortable with.

The CollectionViewLoader

A good place to start is to take a look at public surface area of the CollectionViewLoader type you’ll be extending.

  public abstract class CollectionViewLoader
  {
    public event EventHandler CanLoadChanged;
    public event AsyncCompletedEventHandler LoadCompleted;

    public abstract bool CanLoad { get; }

    public abstract void Load(object userState);
  }

It’s a simple abstract class with one method, one property, and two events. The Load method is responsible for asynchronously loading data into the source collection of the collection view. Since the Load method is asynchronous, it needs to raise a LoadCompleted event when it completes. The CanLoad property tells the DCV whether it can safely invoke the Load method. There are a number of CanXx properties in the ICollectionView interface, and changes to the CanLoad property will propagate to all of them. For example, since re-sorting the DCV will result in a Load call, CanSort will be set to false when CanLoad is false.

The Sample

I’ve also had a number of questions lately about how to use the DCV with the MVVM pattern I proposed in a recent post. This will be a two-birds-with-one-stone sample where I’ll show how to write a custom CollectionViewLoader that works with the MVVM service pattern. It’s worth noting this sample is a variant of the one I published with my original DCV post.

I’ll start with the custom loader code and work back through the rest of the sample.

  public class SampleCollectionViewLoader<TEntity>
    : CollectionViewLoader where TEntity : Entity
  {
    private Action<Action<ServiceLoadResult<TEntity>>, object> _load;
    private Action<object> _cancelLoad;
    private Action<ServiceLoadResult<TEntity>> _onLoadCompleted;

    private object _currentUserState;

    public SampleCollectionViewLoader(
        Action<Action<ServiceLoadResult<TEntity>>, object> load,
        Action<object> cancelLoad,
        Action<ServiceLoadResult<TEntity>> onLoadCompleted)
    {
      if (load == null)
      {
        throw new ArgumentNullException("load");
      }
      if (onLoadCompleted == null)
      {
        throw new ArgumentNullException("onLoadCompleted");
      }

      this._load = load;
      this._cancelLoad = cancelLoad;
      this._onLoadCompleted = onLoadCompleted;
    }

    public override bool CanLoad
    {
      get { return true; }
    }

    private object CurrentUserState
    {
      get
      {
        return this._currentUserState;
      }

      set
      {
        if (this._currentUserState != value)
        {
          if (this._cancelLoad != null)
          {
            this._cancelLoad(this._currentUserState);
          }
        }

        this._currentUserState = value;
      }
    }

    public override void Load(object userState)
    {
      if (!this.CanLoad)
      {
        throw new InvalidOperationException(
                    "Load cannot be called when CanLoad is false");
      }
      this.CurrentUserState = userState;
      this._load(this.OnLoadCompleted, userState);
    }

    private void OnLoadCompleted(ServiceLoadResult<TEntity> result)
    {
      this._onLoadCompleted(result);

      if (this.CurrentUserState == result.UserState)
      {
        this.CurrentUserState = null;
      }

      base.OnLoadCompleted(result);
    }
  }

This custom CollectionViewLoader in this sample is pretty straightforward and follows the pattern used in the DomainCollectionViewLoader to call back into the view model. It has three callbacks; one for loading, one for canceling, and one for load completion. As you can see, the signature of the callbacks differs from the ones in the DomainCollectionViewLoader. This is necessary to work with the service layer in a natural way which I’ll explain more in the next section.

There are a couple more things to note about this implementation. First, I haven’t done anything with the CanLoad property. In the sample I include a IsGridEnabled flag in the SampleViewModel that serves roughly the same purpose (and behaves a little nicer from a UI perspective when using the standard Silverlight DataGrid). Second, the bulk of the code that’s not calling into the view model is related to cancellation. I’ll talk a little more about that at the end.

The next part of the sample to look at is the service interface. It’s pretty simple and encapsulates loading sample entities.

  public interface ISampleService
  {
    EntityContainer EntityContainer { get; }

    void LoadSampleEntities(
      QueryBuilder<SampleEntity> query,
      Action<ServiceLoadResult<SampleEntity>> callback,
      object state);
  }

Next, we’ll take a look at the view model. It’s going to be the place where the SampleCollectionViewLoader, the SampleService, and all the callbacks are tied together.

  public SampleViewModel()
  {
    this._source = new EntityList<SampleEntity>(
      this._service.EntityContainer.GetEntitySet<SampleEntity>());

    this._loader = new SampleCollectionViewLoader<SampleEntity>(
      this.LoadSampleEntities,
      this.CancelLoadSampleEntities,
      this.OnLoadSampleEntitiesCompleted);

    this._view = new DomainCollectionView<SampleEntity>(
      this._loader,
      this._source);

    // Go back to the first page when the sorting changes
    INotifyCollectionChanged notifyingSortDescriptions = 
      this.CollectionView.SortDescriptions;
    notifyingSortDescriptions.CollectionChanged +=
      (sender, e) => this._view.MoveToFirstPage();

    using (this.CollectionView.DeferRefresh())
    {
      this._view.PageSize = 10;
      this._view.MoveToFirstPage();
    }
  }

The source is created using an EntitySet provided by the EntityContainer in the ISampleService. The loader now creates a SampleCollectionViewLoader and passes in three view model callbacks. We’ll take a look at two of those callbacks next.

  private void LoadSampleEntities(
    Action<ServiceLoadResult<SampleEntity>> onLoadCompleted,
    object userState)
  {
    this.IsGridEnabled = false;

    this._service.LoadSampleEntities(
      new QueryBuilder<SampleEntity>().SortAndPageBy(this._view),
      onLoadCompleted,
      userState);
  }

  private void OnLoadSampleEntitiesCompleted(
    ServiceLoadResult<SampleEntity> result)
  {
    this.IsGridEnabled = true;

    if (result.Error != null)
    {
      // TODO: handle errors
    }
    else if (!result.Cancelled)
    {
      this._source.Source = result.Entities;

      if (result.TotalEntityCount != -1)
      {
        this._view.SetTotalItemCount(result.TotalEntityCount);
      }
    }
  }

If you’ve followed my previous posts on the subject (linked prolifically above), these two implementations will look very familiar. The only significant difference is that the loader passes a completion callback and user state through to the LoadSampleEntities method for it to pass to the service layer. When the service load completes, it will tell the loader which will in-turn tell the view model.

A Note on Cancellation

Cancellation is a tricky subject on its own, but I’ll try to address how it fits into this pattern. Since a CollectionViewLoader is only dealing with one set of data, each subsequent load should cancel the previous one. In the sample for the MVVM pattern, I had cancellation in the service layer. It’s an approach that worked on the assumption you only invoke one current load per entity type. It’s pretty easy to see how this assumption fails to scale, though, so other approaches are necessary. If you find yourself using the same load method for multiple purposes, I’d recommend adding a cancel method to the service layer that looks like CancelLoadXx(object userState). You can then invoke this from the cancel callback you pass to the loader.

Summary

Like I mentioned at the beginning of this post, I expect you to write custom CollectionViewLoaders that support the kinds of things you want to do in your view model. Hopefully this post gives you a template to start from. Feel free to customize it however you see fit.

Here’s the source for the sample. It shows a little more detail on things fit together. Let me know what you think and if you have questions.

https://code.msdn.microsoft.com/Writing-a-Custom-e0769d37

So my question is this: “What problem are you solving?”

I think we can all admit any solution where one of the steps is “manually merge” is sub-optimal. This is something I want to fix. If you’ll oblige me, I’d love to hear what you’re doing and why you’re doing it (as a bonus, responding to this post makes it much more likely I’ll address your scenario).

Feel free to add a short comment with your thoughts or email me directly. Thanks.

I’ve put together a reworked version of John’s BookShelf sample to highlight the changes.

The BookShelf Sample

The primary type we’re interested in here is the IBookDataService. Also interesting are the types that implement and consume it. Thankfully this is a small list composed of the interface, the design-time implementation, the actual implementation, and the view model. I’ll make changes to each and try explain the rationale in this post. Typically the deciding factor is whether a type can be returned by a mock or design-time implementation (and to a lesser extent, whether the design is awesome).

In addition, I wrote up some result types that bring a lot of the value of the RIA Operation types to the view model layer. I’ll cover those in a section at the end.

IBookDataService

Since the changes to the service interface drive the changes elsewhere, we should start by looking at the IBookDataService.

  public interface IBookDataService
  {
    EntityContainer EntityContainer { get; }

    void SubmitChanges(
           Action<ServiceSubmitChangesResult> callback,
           object state);

    void LoadBooksByCategory(
           int categoryId,
           QueryBuilder<Book> query,
           Action<ServiceLoadResult<Book>> callback,
           object state);
    void LoadBooksOfTheDay(
           Action<ServiceLoadResult<BookOfDay>> callback,
           object state);
    void LoadCategories(
           Action<ServiceLoadResult<Category>> callback,
           object state);
    void LoadCheckouts(
           Action<ServiceLoadResult<Checkout>> callback,
           object state);
  }

There are a few things worth noting. First, the EntityContainer is available as part of the interface. If you aren’t familiar with it, the EntityContainer is the type the DomainContext uses to store EntitySets, implement change tracking, and compose change sets. Luckily, the EntityContainer is designed such that it can live as easily in a mock implementation as the real one. Adding it to the service layer provides a lot of power while still enabling both separation and testability.

Second, all the callbacks pass a service result type. These types contain a distilled version of their RIA counterparts (LoadOperation, etc.) and I’ll cover them at the end.

Finally, the LoadBooksByCategory method takes both the categoryId and a QueryBuilder as arguments. This not only allows the service layer to filter the books by category, but it also allows the view model layer to put together custom queries that will be run on the server (sorting, paging, etc.).

DesignBookDataService

The design-time service implementation is simple and closely resembles the original version.

  public class DesignBookDataService : IBookDataService
  {
    private readonly EntityContainer _entityContainer =
      new BookClubContext.BookClubContextEntityContainer();

    public EntityContainer EntityContainer
    {
      get { return this._entityContainer; }
    }

    ...

    public void LoadBooksByCategory(
                  int categoryId,
                  QueryBuilder<Book> query,
                  Action<ServiceLoadResult<Book>> callback,
                  object state)
    {
      this.Load(query.ApplyTo(new DesignBooks()), callback, state);
    }

    ...

    private void Load<T>(
                   IEnumerable<T> entities,
                   Action<ServiceLoadResult<T>> callback,
                   object state)
                 where T : Entity
    {
      this.EntityContainer.LoadEntities(entities);
      callback(new ServiceLoadResult<T>(entities, state));
    }
  }

The EntityContainer is the same internal type as the one use in the BookClubContext, but could easily be mocked if the design-time service and generated proxies lived in different assemblies.

The LoadBooksByCategory method applies the query to a static data-set before invoking a generic Load method. The generic version makes sure the entities are contained in the EntityContainer and then asynchronously invokes the callback.

BookDataService

The actual service implementation is greatly simplified and is now much closer to the design-time version.

  public class BookDataService : IBookDataService
  {
    private readonly BookClubContext _context = new BookClubContext();

    ...

    public EntityContainer EntityContainer
    {
      get { return this._context.EntityContainer; }
    }

    ...

    public void LoadBooksByCategory(
                  int categoryId,
                  QueryBuilder<Book> query,
                  Action<ServiceLoadResult<Book>> callback,
                  object state)
    {
      this.Load(
        query.ApplyTo(this._context.GetBooksByCategoryQuery(categoryId)),
        lo =>
        {
          callback(this.CreateResult(lo, true));
        }, state);
    }

    ...

    private void Load<T>(
                   EntityQuery<T> query,
                   Action<LoadOperation<T>> callback,
                   object state)
                 where T : Entity
    {
      ...
      this._context.Load(query, lo =>
        {
          ...
          callback(lo);
        }, state);
    }
    private ServiceLoadResult<T> CreateResult<T>(
                                   LoadOperation<T> op,
                                   bool returnEditableCollection = false)
                                 where T : Entity
    {
      if (op.HasError)
      {
        op.MarkErrorAsHandled();
      }
      return new ServiceLoadResult<T>(
        returnEditableCollection ?
          new EntityList<T>(
            this.EntityContainer.GetEntitySet<T>(),
            op.Entities) :
          op.Entities,
        op.TotalEntityCount,
        op.ValidationErrors,
        op.Error,
        op.IsCanceled,
        op.UserState);
    }
  }

Again we can see the LoadBooksByCategory method applying the query; this time to an EntityQuery. It also creates a callback that it can pass through to the DomainContext.Load method.

It’s worth noting the CreateResult method has the option to return an editable collection or a read-only one. When we take a look at the view model, you’ll be able to see it working against both.

BookViewModel

The view model has changed a number of things to consume the new interface, but it’s all still pretty straightforward.

  public class BookViewModel : ViewModel
  {
    private const int _pageSize = 10;

    private int _pageIndex;

    protected IPageConductor PageConductor { get; set; }
    protected IBookDataService BookDataService { get; set; }

    ... 

    public BookViewModel(
      IPageConductor pageConductor,
      IBookDataService bookDataService)
    {
      PageConductor = pageConductor;
      BookDataService = bookDataService;
      BookDataService.EntityContainer.PropertyChanged +=
        BookDataService_PropertyChanged;

      RegisterCommands();
      LoadData();
    }

    private void BookDataService_PropertyChanged(
                   object sender, PropertyChangedEventArgs e)
    {
      if (e.PropertyName == "HasChanges")
      {
        HasChanges = BookDataService.EntityContainer.HasChanges;
        SaveBooksCommand.RaiseCanExecuteChanged();
      }
    }

    ...

    public void LoadBooksByCategory()
    {
      _pageIndex = 0;
      Books = null;
      if (SelectedCategory != null)
      {
        BookDataService.LoadBooksByCategory(
          SelectedCategory.CategoryID,
          new QueryBuilder<Book>().Take(_pageSize),
          LoadBooksCallback,
          null);
      }
    }

    private void OnLoadMoreBooksByCategory()
    {
      if (SelectedCategory != null)
      {
        _pageIndex++;
        BookDataService.LoadBooksByCategory(
          SelectedCategory.CategoryID,
          new QueryBuilder<Book>()
                .Skip(_pageIndex * _pageSize).Take(_pageSize),
          LoadBooksCallback,
          null);
      }
    }

    public void LoadBooksByTitle()
    {
      _pageIndex = 0;
      Books = null;
      if (SelectedCategory != null)
      {
        BookDataService.LoadBooksByCategory(
          SelectedCategory.CategoryID,
          new QueryBuilder<Book>()
                .Where(b => b.Title.Contains(TitleFilter)),
          LoadBooksCallback,
          null);
      }
    }

    private void LoadBooksCallback(ServiceLoadResult<Book> result)
    {
      if (result.Error != null)
      {
        // handle error
      }
      else if (!result.Cancelled)
      {
        if (Books == null)
        {
          Books = result.Entities as ICollection<Book>;
        }
        else
        {
          foreach (var book in result.Entities)
          {
            Books.Add(book);
          }
        }

        SelectedBook = Books.FirstOrDefault();
      }
    }

    private ICollection<Book> _books;
    public ICollection<Book> Books
    {
      get { return _books; }
      set
      {
        _books = value;
        RaisePropertyChanged("Books");
      }
    }

    ...
  }

The first place to highlight is in the constructor where the view model subscribes to property change events on the EntityContainer. This allows the view model to listen directly for changes made to any of the entities it is working against.

The second point of interest is the three, similarly-implemented load methods. The significant difference between each implementation is the query it composes to pass to the IBookDataService. In all three cases, the composed query will be run on the server.

Finally, the LoadBooksCallback casts result.Entities to an ICollection<Book>. This is because Books is a collection that supports the adding and removing of entities. In this case, the collection is simply aggregating the results of multiple queries, but the same pattern could be used for the creation of new entities. The reason this pattern works is because the BookDataService is returning an EntityList from CreateResult (above), and EntityList knows how to correctly handle the addition and removal of entities.

Service Result Types

I added three result types to the sample (to the Ria.Common project), ServiceInvokeResult, ServiceLoadResult, and ServiceSubmitChangesResult. While the base operation types have some great features, they aren’t convenient to use in mock or design-time implementations. In addition, there is a lot of useful information in these types that is important to return from the service layer. Each of the result types has properties that closely parallel their operation types. For instance, the ServiceLoadResult has properties for the Error and Cancelled states as well as the enumerable Entities. As can be seen in the LoadBooksCallback above, the pattern for consuming the result type is very similar to the standard RIA pattern; check for errors, check for cancelation, and then process the entities.

QueryBuilder and the DomainCollectionView

Though it isn’t apparent in this sample, the QueryBuilder also acts as a bridge between the DomainCollectionView (read about the DomainCollectionView) and the service layer. Each of the query extensions provided for the DCV work against the QueryBuilder as well. For instance, SortAndPageBy could be applied to the query in the view model before passing the QueryBuilder to the service layer.

Summary

I covered a lot in this post and I wouldn’t be surprised if there are still questions to be answered. It’s not my desire to present a canonical MVVM pattern with this post, but the design here is well-worn and a good place to start. Hopefully types, ideas, and patterns in this post prove useful to you. Please let me know what think and if you have any questions.

[Interesting Variations]

Since writing this, there have been a few intrepid developers who’ve written variations on the pattern worth mentioning.

• Remco combined the pattern with my guidance on using Tasks (from the VS Async CTP) to create a Task Based MVVM Sample.
• Colin riffed in a couple directions first combining the pattern with MEF and then splitting it into a number of class libraries.

Breaking Changes

There are a few breaking changes to the API. Most notably, SortPageAndCount has been renamed. It’s a breaking change, but a simple find-replace should set things right again.

• SortAndPageBy replaces SortPageAndCount
  • SortAndPageBy calls SortBy and PageBy respectively
• SortBy replaces Sort
  • SortBy applies OrderBy and ThenBy clauses to the query
• PageBy replaces Page
  • PageBy applies Skip and Take clauses to the query and conditionally requests the TotalEntityCount
• (All the other query extensions have been removed)
  

Bug Fixes

There were a few bug fixes that went in to improve compatibility with third-party controls. I’ve tested the DCV against four suites of controls now, and it works well with all of them. As always, let me know when you find issues.

Sample

A common question in response to the first post was how to implement filtering. It turns out to be pretty easy, so I wanted to make it obvious with some updates to my sample.

I’ve updated the UI to include a search field.

The search button now invokes the search command which calls into the OnSearch method in my SampleViewModel.

  private void OnSearch()
  {
    // This makes sure we refresh even if we're already on the first page
    using (this._view.DeferRefresh())
    {
      // This will lead us to re-query for the total count
      this._view.SetTotalItemCount(-1);
      this._view.MoveToFirstPage();
    }
  }

The OnSearch method resets the total item count and refreshes the view; leading us back into our load callback.

  private LoadOperation<SampleEntity> LoadSampleEntities()
  {
    this.CanLoad = false;

    EntityQuery<SampleEntity> query = this._context.GetAllEntitiesQuery();
    if (!string.IsNullOrWhiteSpace(this.SearchText))
    {
      query = query.Where(e => e.String.Contains(this.SearchText));
    }

    return this._context.Load(query.SortAndPageBy(this._view));
  }

To make sure the filter gets applied on the server, we conditionally add a Where clause to our query based on the content of the SearchText.

That covers the new additions to the DomainCollectionView. Once again we’ve put together a small sample running with server-side filtering, sorting, grouping, and paging. Here’re the sample bits. Let me know if you have any questions.

https://code.msdn.microsoft.com/Server-Side-Filtering-737becda

Stumbling Points

This section describes two specific traps I fell into. It’s not necessarily important for you to understand the details, but I’ll include them just in case you’re interested. Feel free to skip straight to the solution.

My first error was related to sharing enums in RIA. Due to the way enums appear in assembly metadata, the RIA code generator can’t determine whether they exist on the client or not. If you put an enum in a .shared.cs or .shared.vb file, it will quickly result in a compile error. The solution to this issue is simple. Instead of sharing the enum between tiers, just define it on your server and let codegen take care of the rest.

The second error I ran into was using client-side projection properties. In the past I’ve preferred these to using an IValueConverter in my bindings, but this investigation (finally) helped me to realize this approach has adverse effects on RIA validation. When the property being validated is named something other than the property being set (for example, the MyString property would write through to the MyEnum property where validation would occur) the visual control state will not be updated to reflect the error (no fancy red adornment).

The Solution

I eventually ended up using an IValueConverter-based solution. I put a little extra work into it to make it DisplayAttribute-aware since metadata is a commonly-used RIA feature. I wrote a utility to encapsulate most of this, but I’ll go over that piece at the end once you’ve got a grip on how it all fits together. (Similar variants of this solution are available in a number of places, but I wanted to fill in some of the corners that often get ignored)

I applied these changes to the sample I used in this post (https://blogs.msdn.com/b/kylemc/archive/2010/11/12/silverlight-tv-52-ria-services-q-a.aspx) if you want a place to try it out. These steps should work in any scenario, though.

To create the look above, I defined a simple enum with DisplayAttributes on each of the values.

  public enum MyEnum
  {
    [Display(Name = "(please pick a value)")]
    None = 0,
    [Display(Name = "Value 1")]
    Value1 = 1,
    [Display(Name = "Value 2")]
    Value2 = 2,
    [Display(Name = "Value 3")]
    Value3 = 3,
  }

Then I added a property to my entity that used custom validation to ensure a non-zero value is selected.

  [CustomValidation(typeof(Validation), "ValidateMyEnum")]
  [DataMember]
  public MyEnum MyEnum { get; set; }

(My validation is in a shared file in the web project, Validation.shared.cs)

  public static class Validation
  {
    public static ValidationResult ValidateMyEnum(
      MyEnum myEnum, ValidationContext context)
    {
      if (myEnum == MyEnum.None)
      {
        return new ValidationResult(
          "You must pick a value.", new[] { context.MemberName });
      }
      return ValidationResult.Success;
    }
  }

My next step was to define the ComboBox on the client.

  <ComboBox ItemsSource="{StaticResource myEnumNames}"
            SelectedItem="{Binding Path=MyEnum,
                                   Mode=TwoWay,
                                   Converter={StaticResource enumToString}}"
  />

The SelectedItem binding references a converter I instantiate in my page resources.

  <app:EnumToStringValueConverter x:Key="enumToString" />

The code for the converter is simple and leverages the EnumUtility I’ll describe a little later. It is also generic so a single instance can be shared between multiple types of enums.

  public class EnumToStringValueConverter : IValueConverter
  {
    public object Convert(object value, Type targetType,
      object parameter, CultureInfo culture)
    {
      return EnumUtility.GetName(value.GetType(), value);
    }

    public object ConvertBack(object value, Type targetType,
      object parameter, CultureInfo culture)
    {
      return EnumUtility.GetValue(targetType, value.ToString());
    }
  }

The ItemsSource in the ComboBox above uses a static resource I add in my page constructor before parsing the xaml (in InitializeComponent). I’ve used the EnumUtility again to get the names for my enum.

  this.Resources.Add("myEnumNames", EnumUtility.GetNames(typeof(MyEnum)));
  InitializeComponent();

With all the pieces in place (an enum, a property to bind to, a converter, a list of names, and a ComboBox), I now have a ComboBox bound to an enum and validating input.

An Enum Utility

I wrote a utility class to handle most of the heavy lifting here. For each enum type, it iterates through all the values and figures out the names they should be mapped to. The GetName and GetValue methods map back and forth between the two. Here’s the source in case you’re interested.

  public static class EnumUtility
  {
    private static readonly
      IDictionary<Type, IEnumerable<string>> names =
        new Dictionary<Type, IEnumerable<string>>();
    private static readonly
      IDictionary<Type, IEnumerable<object>> values =
        new Dictionary<Type, IEnumerable<object>>();
    private static readonly
      IDictionary<Type, IDictionary<string, object>> namesToValues =
        new Dictionary<Type, IDictionary<string, object>>();
    private static readonly
      IDictionary<Type, IDictionary<object, string>> valuesToNames =
        new Dictionary<Type, IDictionary<object, string>>();

    public static void Initialize(Type type)
    {
      Initialize(type, GetDisplayAttributeName);
    }

    public static void Initialize(
      Type type, Func<FieldInfo, string> getName)
    {
      if (type == null)
      {
        throw new ArgumentNullException("type");
      }

      if (!type.IsEnum)
      {
        throw new ArgumentException("Type must be an enum.", "type");
      }

      if (getName == null)
      {
        throw new ArgumentNullException("getName");
      }

      if (names.ContainsKey(type))
      {
        return;
      }
        
      List<string> tempNames = new List<string>();
      List<object> tempValues = new List<object>();
      Dictionary<string, object> tempNamesToValues =
        new Dictionary<string, object>();
      Dictionary<object, string> tempValuesToNames =
        new Dictionary<object, string>();

      foreach (FieldInfo fi in
        type.GetFields(BindingFlags.Public | BindingFlags.Static))
      {
        string name = getName(fi);
        object value = fi.GetValue(null);

        tempNames.Add(name);
        tempValues.Add(value);
        tempNamesToValues[name] = value;
        tempValuesToNames[value] = name;
      }

      names[type] = tempNames;
      values[type] = tempValues;
      namesToValues[type] = tempNamesToValues;
      valuesToNames[type] = tempValuesToNames;
    }

    private static string GetDisplayAttributeName(FieldInfo fi)
    {
      DisplayAttribute displayAttribute = 
       (DisplayAttribute)fi.GetCustomAttributes(
         typeof(DisplayAttribute), false).FirstOrDefault();

      return (displayAttribute == null) ? fi.Name : displayAttribute.Name;
    }

    public static IEnumerable<string> GetNames(Type type)
    {
      Initialize(type);
      return names[type];
    }

    public static IEnumerable<object> GetValues(Type type)
    {
      Initialize(type);
      return values[type];
    }

    public static string GetName(Type type, object value)
    {
      Initialize(type);
      return valuesToNames[type][value];
    }

    public static object GetValue(Type type, string name)
    {
      Initialize(type);
      return namesToValues[type][name];
    }
  }

Bind to an EntitySet

As of SP1, we improved binding support for EntitySets. EntitySets are aggregating, un-ordered collections. That means every time an entity is loaded by your DomainContext it will be added to its corresponding EntitySet. Binding to an EntitySet will give you a great view of every entity of a specific type your DomainContext knows about. Adding to or removing from an EntitySet will result in calls to the insert and delete operations being invoked when you submit changes to your DomainService.

Making an EntitySet available in your view model would look like this.

  public EntitySet<SampleEntity> EntitySet
  {
    get { return this.Context.SampleEntities; }
  }

Bind to an EntityCollection

In SP1, we also improved binding support for EntityCollections. EntityCollections are collections of entities associated with a specific Entity. In a manner similar to the EntitySet, an EntityCollection will be updated as new entities are loaded into your DomainContext. Each will be added to the EntityCollection of the Entity it is associated with. Adding and removing from an EntityCollection will only update the association. Most of the time, this results in an update operation being invoked when you submit changes.

Since EntityCollections are tied to specified Entities, having a property on your view model seems like an uncommon case. Nevertheless, making an EntityCollection available in your view model would look like this.

  public EntityCollection<SampleEntity> EntityCollection
  {
    get { return this.CurrentEntity.AssociatedEntities; }
  }

Bind to an EntityList

EntityList is a type new to SP1 and can be found in Microsoft.Windows.Data.DomainServices in the Toolkit. An EntityList is an observable collection backed by an EntitySet. The Source property on the EntityList defines the entities it contains, and it will not update as new entities are loaded into your DomainContext. It will update if entities it contains are deleted from the EntitySet or when entities are added or removed from its Source collection. Adding to an EntityList will behave in one of two ways. If the entity already exists in the backing EntitySet, then it is just added to the list. If it does not exist, then it will be added to the EntitySet as well. Removing from the EntityList will always remove the entity from the backing EntitySet. Binding to an EntityList is a great option when you only want to see a subset of the entities your DomainContext knows about.

Making an EntityList available in your view model would look like this.

  private EntityList<SampleEntity> _entityList;
  public EntityList<SampleEntity> EntityList
  {
    get
    {
      if (this._entityList == null)
      {
        this._entityList = new EntityList<SampleEntity>(
          this.Context.SampleEntities);
      }
      return this._entityList;
    }
  }

  private void LoadSampleEntities()
  {
    this.EntityList.Source =
      this.Context.Load(this.Context.GetAllEntitiesQuery()).Entities;
  }

Bind to an ICollectionView

In case you’re not familiar with the ICollectionView interface, it’s used by a number of components (DataGrid, DataForm, etc.) as a view over a source collection. For example, when you bind DataGrid.ItemsSource to a collection, it will create a collection view behind the scenes to interact with. Instead of just having the control instantiate a view behind the scenes, you have the option of making the ICollectionView available for binding directly from your view model.

It may not be readily apparent why you’d do this, but as you did into the interface, you’ll noticed it has a number of properties for defining how the view presents the source collection. You can control the sorting, grouping, and filtering as well as which item is selected; all from the ICollectionView.

In Silverlight, most collection view implementations are internal. Fortunately, there’s an easy way of letting the framework instantiate the correct view for the collection that uses the CollectionViewSource.

  private static ICollectionView CreateView(IEnumerable source)
  {
    CollectionViewSource cvs = new CollectionViewSource();
    cvs.Source = source;
    return cvs.View;
  }

Making an ICollectionView available in your view model would look like this.

  private ICollectionView _collectionView;
  public ICollectionView CollectionView
  {
    get
    {
      if (this._collectionView == null)
      {
        this._collectionView = CreateView(this.Context.SampleEntities);
      }
      return this._collectionView;
    }
  }

The downside of using this approach is that all the existing collection view implementations only operate over the in-memory collection. That means you have to pull all the data to Silverlight before you apply sorting or filtering.

Bind to a DomainCollectionView

To address the limitations of existing ICollectionView implementations we’ve added the DomainCollectionView in SP1 in Microsoft.Windows.Data.DomainServices in the Toolkit. It is designed to allow for asynchronous sorting, grouping, and paging, and works with all the controls that use the collection view interfaces. This enables you to page over data on your server using the core data controls.

The setup for a DomainCollectionView is slightly more complicated than some of these other options. This is because it requires load callbacks as well as a source collection. These callbacks can be implemented just like any other load operation in your view model.

  private LoadOperation<SampleEntity> LoadSampleEntities()
  {
    return this.Context.Load(
      this.Context.GetAllEntitiesQuery().SortPageAndCount(
        this.DomainCollectionView));
  }

  private void OnLoadSampleEntitiesCompleted(LoadOperation<SampleEntity> op)
  {
    if (op.HasError)
    {
      // TODO: handle errors
      op.MarkErrorAsHandled();
    }
    else if (!op.IsCanceled)
    {
      this.EntityList.Source = op.Entities;

      if (op.TotalEntityCount != -1)
      {
        this.DomainCollectionView.SetTotalItemCount(op.TotalEntityCount);
      }
    }
  }

With callbacks defined, making a DomainCollectionView available in your view model would look like this.

  private DomainCollectionView<SampleEntity> _domainCollectionView;
  public DomainCollectionView<SampleEntity> DomainCollectionView
  {
    get
    {
      if (this._domainCollectionView == null)
      {
        this._domainCollectionView =
          new DomainCollectionView<SampleEntity>(
            new DomainCollectionViewLoader<SampleEntity>(
              this.LoadSampleEntities,
              this.OnLoadSampleEntitiesCompleted),
            this.EntityList);
      }
      return this._domainCollectionView;
    }
  }

This is just enough to get you started with the DomainCollectionView, but it leaves out most of the details. In this next post, I go much more in-depth and explain the design and core API.

https://blogs.msdn.com/b/kylemc/archive/2010/12/02/introducing-an-mvvm-friendly-domaindatasource-the-domaincollectionview.aspx

Are there other options?

There are always other options, but I’m not sure I’d recommend using them. One common alternative would be to make the property types of these collections their respective interfaces (for instance IEnumerable or ICollectionView). This can reduce coupling and give you more flexibility. Also, since most Silverlight controls that bind to collections are just looking for interfaces, the impact is negligible.

If you have other suggestions, I’d love to hear them. Hope this overview helps.