Cinch V1 Documentation

Cinch V1 is a MVVM framework that provides a number of attached behaviours/UI services and a number of helpers. It was aimed at writing highly testable ViewModels that were written by inheriting from well designed Cinch v1 base ViewModels where a lot of the work had already been done for the user. Cinch V1 used the Unity DI/IOC container out of the box, but could be made to work with any other IOC container fairly easily.

It had several UI services and also provided test doubles for these services, the following core services are available within Cinch V1

• Logging Service
• MessageBox Service
• Open File Service
• Save File Service
• Popup Window Service

It was written for VS2008 and was written before Microsoft formalized a lot of the things WPF developers were already doing. As such since Cinch V1 was released there are better ways to do a few things. Cinch V2 however makes use of all the newer features that are now available both in the Blend Interactivity Dll and the .NET 4.0 Dlls.

• 1 Attached Behaviours
  • 1.1 View Lifecycle Events
  • 1.2 Numeric Textbox Attached Behaviour
  • 1.3 Attached Command Behaviour
• 2 Model/ViewModel Basics
  • 2.1 INotifyPropertyChanged : Dealing with the INPC Smell, No more magic strings
  • 2.2 IEditableObject Support
  • 2.3 View Model Modes
  • 2.4 Closeable ViewModels
  • 2.5 Doing MenuItems the MVVM way
  • 2.6 Validation
    • 2.6.1 Validation Rules/IDataErrorInfo Integration
  • 2.7 DI/IOC
    • 2.7.1 Exposed services
      • 2.7.1.1 Logging service
      • 2.7.1.2 MessageBox service
      • 2.7.1.3 Open File service
      • 2.7.1.4 Save File service
      • 2.7.1.5 Popup window service
• 3 Developing Models Using Cinch
• 4 Developing ViewModels Using Cinch
  • 4.1 Choosing a ViewModel Base Class
  • 4.2 ViewModelBase Class
  • 4.3 How To Use The Exposed Services
    • 4.3.1 Logging service
    • 4.3.2 MessageBox service
    • 4.3.3 Open File service
    • 4.3.4 Save File service
    • 4.3.5 Popup window service
  • 4.4 Background Tasks
  • 4.5 Mode Support
• 5 Events
  • 5.1 WeakEvent Creation
  • 5.2 WeakEvent Subscription
• 6 Disconnected Messaging
  • 6.1 Mediator Messaging
• 7 Helpers
  • 7.1 Dispatcher extension methods
  • 7.2 App.DoEvents
  • 7.3 Background Tasks
  • 7.4 DispatcherNotifiedObservableCollection
  • 7.5 Setting Focus
• 8 Unit Testing
  • 8.1 Testing Commands
  • 8.2 Testing Mediator
  • 8.3 Testing Background Worker Tasks
  • 8.4 Testing The Validity Of IDataErrorInfo Supporting Objects
  • 8.5 Testing The State Of IEditableObject Supporting Objects
  • 8.6 Testing Services
    • 8.6.1 IMessageBox Service
    • 8.6.2 IOpenFileService Service
    • 8.6.3 ISaveFileService Service
    • 8.6.4 IUIVisualizerService Service

Cinch V2 Documentation

With Cinch V2, I swapped out the standard IOC container support for the use of Managed Extensibility Framework (MEF), and I also took a dependency on the fabulous MEFedMVVM project by my good friend Marlon Grech. Marlon did an amazing job with MEFedMVVM and it is thanks to MEFedMVVM that Cinch V2 is able to offer such great design time support for services.

I also took the time to try and create a View 1st workspace arrangement for WPF, and update all attached properties to use the newest best practices of using the Blend Interactivity Behaviours/Triggers/Actions.

The following are now available in Cinch V2 where these replace the Cinch V1 attached behaviour DPs, and there are some new ones too.

Behaviours

• NumericTextBoxBehaviour (WPF Only)
• SelectorDoubleClickCommandBehavior (WPF Only)
• TextBoxFocusBehavior (WPF Only)

Triggers

• CompletedAwareCommandTrigger
• CompletedAwareGotoStateCommandTrigger
• EventToCommandTrigger

Actions

• CommandDrivenGoToStateAction

At the same time I also made Cinch support Silverlight 4 or above. Cinch V2 offers many of the same features that Cinch V1 one had, like the choice of ViewModel base classes, and DataWrapper, and there are some services which were fine in Cinch V1, that have simply been made available via MEF. This is good for everyone as these are good features that worked just fine. What is new is that there are a number of new services, and as I stated there is now support for design time data, and for Silverlight of course. I have not discussed Unit testing in any of the new Cinch V2 material, as it has largely stayed the same as Cinch V1, though where I have introduced new services I have also included new test doubles (essentially pre built mocks for you to use) in the Cinch V2 codebase.

• 1 What's New
• 2 What Will Break If I Am A Cinch V1 User
• 3 MEFedMVVM And ViewModel/Service Resolution
  • 3.1 What's MEF
  • 3.2 Introducing MefedMVMM
  • 3.3 The Basic Idea
  • 3.4 View-ViewModel Resolution
  • 3.5 Service Resolution
  • 3.6 View Context
• 4 Developing Models Using Cinch
  • NOTE : This is no longer possible in Cinch V2
• 5 Developing ViewModels Using Cinch
  • 5.1 Choosing a ViewModel Base Class (No Change to available base classes types since Cinch V1, but there are differences in implementation)
  • 5.2 Background Tasks (No Change since Cinch V1)
  • 5.3 Mode Support (No Change since Cinch V1)
• 6 Model/ViewModel Basics
  • 6.1 INotifyPropertyChanged : Dealing with the INPC Smell, No more magic strings (No Change since Cinch V1)
  • 6.2 IEditableObject Support (No Change since Cinch V1)
  • 6.3 View Model Modes (No Change since Cinch V1)
  • 6.4 Closeable ViewModels (No Change since Cinch V1)
  • 6.5 Doing MenuItems the MVVM way (No Change since Cinch V1)
  • 6.1 Validation
    • 6.1.1 Validation Rules/IDataErrorInfo Integration (No Change since Cinch V1)
• 7 Events
  • 7.1 WeakEvent Creation (No Change since Cinch V1)
  • 7.2 WeakEvent Subscription (No Change since Cinch V1)
• 8 Disconnected Messaging
  • 8.1 Mediator Messaging (Small change since Cinch V1, you now need to register Manually)
• 9 Services/UI Services
  • 9.1 Core Services
    • VisualStateManagerService (SL and WPF)
    • SLMessageBoxService (SL only)
    • ChildWindowService (SL only)
    • ViewAwareStatus (SL version)
    • ViewAwareStatus (WPF version)
    • WPFMessageBoxService (WPF only)
    • WPFOpenFileService (WPF only)
    • WPFSaveFileService (WPF only)
    • WPFUIVisualizerService (WPF only)
  • 9.2 UI Services
• 10 New Stuff For CinchV2
  • 10.1 SimpleCommand
  • 10.2 Actions/Triggers
    • NumericTextBoxBehaviour (WPF Only)
    • SelectorDoubleClickCommandBehavior (WPF Only)
    • TextBoxFocusBehavior (WPF Only)
    • CompletedAwareCommandTrigger (SL and WPF)
    • CompletedAwareGotoStateCommandTrigger (SL and WPF)
    • EventToCommandTrigger (SL and WPF)
    • CommandDrivenGoToStateAction (SL and WPF)
  • 10.3 Workspaces
  • 10.4 Extra Threading Helpers
  • 10.5 Extra Utilities
    • PropertyChangedEventManager for SL
    • BindingEvaluator for WPF
    • ObservableDictionary for WPF
    • TreeHelper for WPF,
    • ArgumentValidator for both SL and WPF
    • Dispatcher extension methods (No Change since Cinch V1)
    • App.DoEvents (No Change since Cinch V1)
    • Background Tasks (No Change since Cinch V1)
    • dispatcherNotifiedObservableCollection (No Change since Cinch V1)
• 11 Unit Testing (No Change since Cinch V1)
  • 11.1 Testing Commands
  • 11.2 Testing Mediator
  • 11.3 Testing Background Worker Tasks
  • 11.4 Testing The Validity Of IDataErrorInfo Supporting Objects
  • 11.5 Testing The State Of IEditableObject Supporting Objects
  • 11.6 Testing Services
    • 11.6.1 IMessageBox Service
    • 11.6.2 IOpenFileService Service
    • 11.6.3 ISaveFileService Service
    • 11.6.4 IUIVisualizerService Service
    • NOTE : There are additional test doubles for ViewAwareStatusWindow (WPF Only), and TestViewAwareStatus (UserControl so for Silverlight and WPF), and TestVVSMService

A Few Notes About BLEND

One user reported some strange issues using MefedMVVM and Cinch together with Blend, and was getting multiple contract imports occurring. This ended up being down to BLEND keeping a cached copy of some Dlls in a cached folder. This is one gotcha that I thought I should write down here in case anyone comes across it.

So if you find MEF catalog issues please do the following 2 things:

• Ensure the Blend cache is cleaned up, the location of which may vary depending on what OS you are running. I am running Win7 and for me that is located here : " C:\Users\barbers\AppData\Local\Microsoft\Expression\Blend\Project", but for the reporter of the error this was located at "C:\Users\xxx\AppData\Local\Microsoft\Expression\Blend"
• Another gotcha is if you are working with references, you may come across MEF errors then too, you can see Marlons blog for a solution to this, which involves "CopyLocal=false" fix, see Marlons Blog MEF DeploymentCatalog and Reference assemblies

Cinch V2 Related Demo Articles

• How to convert a Silverlight Navigation Application to use MVVM using Cinch V2. Which basically shows you how to use the Silverlight inbuilt navigation features with CinchV2 for Silverlight
• Disecting The WPF Demo App
• Disecting The SL4 Demo App

Cinch V2 Working With PRISM 4

Since the introduction of Cinch V2 and the latest release of PRISM (which uses MEF) Cinch V2 and PRISM can work together very easily, as such I have created a couple of demo applications which show case Cinch V2 working with PRISM 4 features like Regions/Module. The links below will talk you through that, and you can see what the 2 demo apps look like on the Cinch Home page here at codeplex.

• 1 Demo App1 : Using PRISM regions/modules
  • 1.1 DEMO 1 : What does it look like?
  • 1.2 DEMO 1 : How does it all work?
    • 1.2.1 DEMO 1 : The shell
    • 1.2.2 DEMO 1 : Custom region adaptor
    • 1.2.3 DEMO 1 : Bootstrapper
    • 1.2.4 DEMO 1 : Welcome View
    • 1.2.5 DEMO 1 : Image View
• 2 Demo App1 : Using PRISM regions with custom region adaptors
  • 2.1 DEMO 1 : What does it look like?
  • 2.2 DEMO 1 : How does it all work?
    • 2.2.1 DEMO 1 : The shell
    • 2.2.2 DEMO 1 : Bootstrapper
    • 2.2.3 DEMO 1 : Welcome Module
    • 2.2.4 DEMO 1 : Image Module

Cinch V1/V2 Common Code Generator Documentation

There is a code generator application that can be used to create CinchV1/V2 ViewModels. It was originally written for Cinch V1, so you will find it in the CinchV1 folder in the source code. Below is a list of the documentation for the code generator

• 1 Introductions
• 2 Prerequisites
• 3 Steps To Follow To Start Churning Out Code
• 4 How It All Works, For Those That Care
  • 4.1 Structure Of The App
  • 4.2 ViewModel Persistence To/From XML
  • 4.3 Referenced Assembly Management
  • 4.4 Property Management
  • 4.5 Code Compilation
  • 4.6 The Stucture Of The Generated Code