catel.4.2.0.documentation_

8/18/2019 catel.4.2.0.documentation_

1/387

1. Catel documentation Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.1.1 Why Catel? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.1.2 Support for multiple platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.1.2.1 Caveats in WPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.1.2.2 Caveats in Silverlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.1.2.3 Caveats in Windows Phone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.1.2.4 Caveats in Windows RT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.1.2.5 Caveats in Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.1.2.6 Caveats in iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.1.3 Introduction to data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.1.4 Introduction to MVVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.1.4.1 MVVM framework comparison sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201.1.4.2 Different interpretations of MVVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.1.4.3 Validation in model or view model? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.1.4.4 Introduction to MVVM and models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241.1.4.5 Creating view models with Catel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241.1.4.6 Introduction to services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311.1.4.7 Introduction to the nested user controls problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331.1.4.8 Introduction to unit testing in MVVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

1.1.5 Introduction to MVC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421.2 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

1.2.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421.2.2 MVVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

1.3 Setup, deployment and projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471.3.1 Getting prerelease (beta) versions via NuGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

1.3.2 Stepping through the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491.3.3 Compiling from source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491.3.4 Code snippets & templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

1.3.4.1 Using the code snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501.3.4.2 Using the item templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501.3.4.3 Using the project templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

1.3.5 Updating to a new version via NuGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531.3.6 Update guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

1.3.6.1 Catel 4.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541.3.6.2 Catel 4.1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

1.4 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591.4.1 Quick introduction for developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591.4.2 Getting started with WPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

1.4.2.1 Creating the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621.4.2.2 Creating the models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651.4.2.3 Serializing data from/to disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

1.4.2.4 Creating the view models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741.4.2.5 Creating the views (user controls) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781.4.2.6 Creating the views (windows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801.4.2.7 Hooking up everything together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821.4.2.8 Finalizing the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

1.5 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951.5.1 WPF Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

1.5.1.1 Advanced WPF example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961.5.1.2 Authentication example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981.5.1.3 Browser application example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991.5.1.4 Master/detail example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001.5.1.5 Multilingual example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001.5.1.6 MVVM communication styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011.5.1.7 Person application WPF example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021.5.1.8 Validation example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031.5.1.9 Viewmodel lifetime example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

1.5.2 Silverlight examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051.5.2.1 Advanced Silverlight example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051.5.2.2 Navigation example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1081.5.2.3 Nested user controls example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091.5.2.4 Person application Silverlight example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

1.5.3 Windows Phone examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111.5.3.1 Bing maps example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111.5.3.2 Sensors example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131.5.3.3 Shopping list example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

1.5.4 Open source using Catel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161.6 Problem solving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161.7 Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1191.8 Catel.Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

1.8.1 ApiCop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121


2/387

1.8.1.1 Cops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241.8.1.2 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241.8.1.3 Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

1.8.2 Argument checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1261.8.3 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1271.8.4 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1301.8.5 Data handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

1.8.5.1 ObservableObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331.8.5.2 DispatcherObservableObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341.8.5.3 ModelBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

1.8.5.4 Using ModelBase as base for entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381.8.5.5 Advanced property change notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391.8.5.6 WCF services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

1.8.6 Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421.8.7 IoC (ServiceLocator and TypeFactory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

1.8.7.1 Dependency injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471.8.7.2 Introductions to IoC components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

1.8.7.2.1 Introduction to the ServiceLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1521.8.7.2.2 Introduction to the TypeFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1531.8.7.2.3 Introduction to DependencyResolver and DependencyResolverManager . . . . . . . . . . . . . . . . . . . . . . 1551.8.7.2.4 Ensuring integrity of the ServiceLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

1.8.7.3 Automatic type registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1611.8.7.3.1 Automatically registering types using attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1611.8.7.3.2 Automatically registering types using conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

1.8.7.4 Setting up the ServiceLocator using configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1631.8.7.5 Replacing the default components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

1.8.8 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661.8.8.1 Log listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1681.8.8.1.1 Batch log listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1681.8.8.1.2 ConsoleLogListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1701.8.8.1.3 DebugLogListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1711.8.8.1.4 EventLogListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1711.8.8.1.5 Event Tracing for Windows (ETW) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721.8.8.1.6 FileLogListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721.8.8.1.7 RollingInMemoryLogListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1731.8.8.1.8 SeqLogListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

1.8.8.2 Customizing listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751.8.8.3 Creating log listeners via configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751.8.8.4 Integration with external loggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

1.8.8.4.1 Log4net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761.8.8.4.2 NLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

1.8.8.5 Anotar.Catel.Fody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

1.8.9 Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791.8.9.1 MessageBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1801.8.9.2 Message mediator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1811.8.9.3 Messaging via attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

1.8.10 Multilingual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1831.8.11 Parallel invocation and tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1861.8.12 Preventing memory leaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

1.8.12.1 Change notification wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871.8.12.2 Weak events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

1.8.13 Reflection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1901.8.14 Scoping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1911.8.15 Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

1.8.15.1 Introduction to serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1921.8.15.2 Specifying what gets serialized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941.8.15.3 Customizing serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011.8.15.4 Supported serializers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

1.8.15.4.1 BinarySerializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2041.8.15.4.2 JsonSerializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2041.8.15.4.3 XmlSerializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

1.8.16 Thread safe code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061.8.17 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

1.8.17.1 Validation via validate methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2101.8.17.2 Validation via data annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2101.8.17.3 Validation via special model validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111.8.17.4 Validation via IValidator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2121.8.17.5 Using the validation context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2151.8.17.6 Getting a summary of validation results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2161.8.17.7 Deferring validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

1.9 Catel.MVVM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171.9.1 Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218


3/387

1.9.2 Behaviors & triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2191.9.2.1 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2201.9.2.2 AutoCompletionBehavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221.9.2.3 AutoScroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231.9.2.4 DelayBindingUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231.9.2.5 DoubleClickToCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2241.9.2.6 EventToCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251.9.2.7 Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2261.9.2.8 FocusFirstControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2271.9.2.9 FocusOnKeyPress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

1.9.2.10 HideUntilViewModelLoaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281.9.2.11 KeyPressToCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281.9.2.12 MouseInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291.9.2.13 Navigate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291.9.2.14 NumericTextBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301.9.2.15 SelectTextOnFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301.9.2.16 UpdateBindingOnPasswordChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2311.9.2.17 UpdateBindingOnTextChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

1.9.3 Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2321.9.3.1 Property bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2331.9.3.2 Command bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

1.9.4 Commands & events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2351.9.4.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2361.9.4.2 CommandManager and command containers (Application-wide commands) . . . . . . . . . . . . . . . . . . . . . . . . 2371.9.4.3 Asynchronous commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2411.9.4.4 Commands authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

1.9.4.5 Hooking a command to validation automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2441.9.5 Converters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2451.9.6 Designers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

1.9.6.1 Design-time view models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2481.9.6.2 Running code at design-time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

1.9.7 Handling application initialization parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2521.9.8 Locators and naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

1.9.8.1 ViewModelLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2531.9.8.2 ViewLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2551.9.8.3 UrlLocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2571.9.8.4 Naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

1.9.9 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2601.9.9.1 AccelerometerService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2601.9.9.2 CameraService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611.9.9.3 CompassService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2641.9.9.4 GyroscopeService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

1.9.9.5 LocationService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2671.9.9.6 MessageService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2681.9.9.7 NavigationService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2701.9.9.8 OpenFileService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2721.9.9.9 PleaseWaitService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2731.9.9.10 ProcessService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2751.9.9.11 SaveFileService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2761.9.9.12 SchedulerService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2771.9.9.13 SelectDirectoryService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2771.9.9.14 SplashScreenService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2781.9.9.15 UIVisualizerService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2811.9.9.16 VibrateService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2831.9.9.17 ViewExportService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

1.9.10 View models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2841.9.10.1 Creating a basic view model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2851.9.10.2 Creating a view model that watches over other view models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

1.9.10.3 Creating a view model with a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2891.9.10.4 Creating a view model with a model and mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2931.9.10.5 Mapping properties from view to view model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2961.9.10.6 Nested view models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2981.9.10.7 Validation in view models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2981.9.10.8 Advanced view models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

1.9.10.8.1 Keeping view models alive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3031.9.10.8.2 Exposing properties of a model automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3031.9.10.8.3 Determine the view model type dynamically at runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3051.9.10.8.4 Controlling the instantiation of view models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

1.9.11 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3071.9.11.1 Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

1.9.11.1.1 Activities (pages) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3101.9.11.1.2 Fragments (user controls) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312


4/387

1.9.11.2 iOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3141.9.11.3 XAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

1.9.11.3.1 Window and DataWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3141.9.11.3.2 UserControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3171.9.11.3.3 MVVM behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3221.9.11.3.4 Validation controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3231.9.11.3.5 Using external controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3251.9.11.3.6 Advanced information about views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3291.9.11.3.7 Customizing DataContext subscription behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

1.9.11.4 Tips & tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

1.9.11.4.1 Finding the view of a view model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3361.10 Catel.Mvc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3371.10.1 Configuring dependency injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

1.11 Catel.Extensions.Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3391.11.1 Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

1.11.1.1 StackGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3391.11.1.2 TabControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3401.11.1.3 TraceOutputControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3401.11.1.4 WatermarkTextBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

1.11.2 Pixel shaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3421.11.3 StyleHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3431.11.4 Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

1.12 Catel.Extensions.CSLA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3451.13 Catel.Extensions.Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

1.13.1 Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3451.14 Catel.Extensions.DynamicObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

1.15 Catel.Extensions.EntityFramework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3471.15.1 Getting started with Entity Framework in Catel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3471.15.2 Using the DbContextManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3501.15.3 Using the repositories and unit of work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3511.15.4 Using the ModelBase as base class for code-first entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3531.15.5 Using stored procedures and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

1.16 Catel.Extensions.FluentValidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3541.17 Catel.Extensions.Interception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

1.17.1 Method interception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3551.17.2 Property interception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

1.18 Catel.Extensions.Memento . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3611.18.1 Memento and collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3631.18.2 Memento and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3631.18.3 Memento and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

1.19 Catel.Extensions.Prism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3661.19.1 Using the bootstrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

1.19.2 Declaring modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3711.19.3 Module catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3721.19.3.1 CompositeModuleCatalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3721.19.3.2 DownloadingModuleCatalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3731.19.3.3 NuGetBasedModuleCatalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3731.19.3.4 SafeDirectoryModuleCatalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

1.19.4 Translating or customizing the initialization task messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3771.20 Catel.Extensions.Wcf.Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3771.21 Catel.Fody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

1.21.1 Weaving properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3791.21.2 Weaving argument checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3811.21.3 Exposing properties on view models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3821.21.4 XmlSchema generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

1.22 Catel.ReSharper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3851.22.1 Checking arguments of a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3851.22.2 Converting regular properties into Catel properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

1.23 Reference documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387


5/387

Catel documentation Home

Welcome to the documentation of Catel. The framework consists of several projects. Each project has it's reference documentation. The actual

technical documentation is available in the downloads sections. However, the wiki contains some real-life examples and additional explanation of

some of the features of Catel.

Supported platformsLooking for documentation of other versions?Articles or documentation?Explanation about the documentation

Catel is an application development platform with the focus on MVVM (WPF, Silverlight, Windows Phone and WinRT) and MVC (ASP.NETMVC). The goal of Catel is to provide a complete set of modular functionality for Line of Business applications written in any .NET technology,from client to server.

Catel distinguishes itself by unique features to aid in the development of MVVM applications and server-side application development. Since Catelfocuses on Line of Business applications, it provides professional support and excellent documentation which ensures a safe bet by professionalcompanies and developers.

Besides the core of Catel, lots of extensions are available so developers can pick whatever they need for their applications to be built. Amongthese extensions are support for Dynamic Objects, Entity Framework, Fluent Validation, Memento patterns and Prism.

Below is a visual representation of the available blocks in Catel:

Supported platforms

The following platforms are supported by Catel:

Don't want to read much? Make sure that you at least read the with the absolute basicsquick introduction


6/387

Looking for documentation of other versions?

Catel LATEST

Catel 4.1Catel 4.0Catel 3.9Catel 3.8Catel 3.7Catel 3.6Catel 3.5

Articles or documentation?

You have probably also found the articles on The Code Project. These articles are meant to be an introduction to a specific field of techniques that

can be found inside Catel. If you are looking for documentation, this is the place to be.

Are you missing documentation?

If you are missing documentation or feel that documentation is out of date, please let us know and we will will fix it!

Explanation about the documentation

You can either navigate through the left bar or via the search at the right top. Below are the top parts of the documentation:

For detailed information about platform support, see Platform support explanation

Updating from an older version? Check out the update guides

Don't forget to take a look at the code snippets and project templates, they will make your life much easier

https://catelproject.atlassian.net/wiki/display/CTL41https://catelproject.atlassian.net/wiki/display/CTL40https://catelproject.atlassian.net/wiki/display/CTL39https://catelproject.atlassian.net/wiki/display/CTL38https://catelproject.atlassian.net/wiki/display/CTL37https://catelproject.atlassian.net/wiki/display/CTL36/Catel+documentation+Homehttps://catelproject.atlassian.net/wiki/display/CTL35/Catel+documentation+Homehttps://catelproject.atlassian.net/wiki/pages/createpage.action?spaceKey=CTL&title=Platform+support+explanation&linkCreation=true&fromPageId=622595https://catelproject.atlassian.net/wiki/pages/createpage.action?spaceKey=CTL&title=Platform+support+explanation&linkCreation=true&fromPageId=622595https://catelproject.atlassian.net/wiki/display/CTL35/Catel+documentation+Homehttps://catelproject.atlassian.net/wiki/display/CTL36/Catel+documentation+Homehttps://catelproject.atlassian.net/wiki/display/CTL37https://catelproject.atlassian.net/wiki/display/CTL38https://catelproject.atlassian.net/wiki/display/CTL39https://catelproject.atlassian.net/wiki/display/CTL40https://catelproject.atlassian.net/wiki/display/CTL41


7/387

IntroductionFAQSetup, deployment and projectsGetting startedExamplesProblem solvingPerformance considerationsCatel.CoreCatel.MVVMCatel.Mvc

Catel.Extensions.ControlsCatel.Extensions.CSLACatel.Extensions.DataCatel.Extensions.DynamicObjectsCatel.Extensions.EntityFrameworkCatel.Extensions.FluentValidationCatel.Extensions.InterceptionCatel.Extensions.MementoCatel.Extensions.PrismCatel.Extensions.Wcf.ServerCatel.FodyCatel.ReSharperReference documentation

Introduction

Welcome to the introduction of Catel. Catel is a framework (or enterprise library, just use whatever you like) with data handling, diagnostics,logging, WPF controls, and an MVVM-framework. So Catel is more than "just" another MVVM-framework or some nice Extension Methods thatcan be used. It's more like a library that you want to include in all the XAML applications you are going to develop in the near future.

It's important to realize that Catel is not just another Extension Methods library, nor only an MVVM-framework, but it is a combination of basic datahandling, useful controls, and an MVVM-framework.

Why another framework?

You might be thinking: why another framework, there are literally thousands of them out there. Well, first of all, thousands of them is quite a lot,let's just say there are hundreds of them. A few years ago, the lead developer of Catel was using serialization to serialize data from/to disk. But,as he noticed, he had to take care of different versions after every release. After every release, he had to take care of the serialization andbackwards compatibility. Also, he had to implement some very basic interfaces (such as INotifyPropertyChanged) for every data object. Then, hedecided to write a base class for data handling which can take care of different versions and serialization by itself, and implements the most basicinterfaces of the .NET Framework out of the box. The article was published on CodeProject as DataObjectBase.

Then, he was working on a WPF project with five other developers and needed an MVVM-framework since the application was not using MVVM

at the moment. Writing an MVVM-framework was no option because there were so many other frameworks out there. But, after looking at some

Open-Source MVVM-frameworks (such as the excellent Cinch framework, which was the best one we could find), none of them seemed to be a

real option. Creating the View Models was too much work, and the View Models still contained lots of repetitive code in, for example, the property

definitions. After taking a closer look at the source code of Cinch and other frameworks, the lead developer thought: if we use the DataObjectBase

published before as the base for a View Model class, it should be possible to create a framework in a very short amount of time.

Then, all other developers of the team he was working on the project got enthusiastic, and then the whole team decided to merge their personal

libraries into one big enterprise library, and Catel was born.

Why use this framework?

Before reading any further, it's important to know why you should use the framework. Below are a few reasons why Catel might be interesting foryou:

Catel is Open-Source. This way, you can customize it any way you want. If you want a new feature request, and the team does not

respond fast enough, you can simply implement it yourself.

The codebase for Catel is available on GitHub. This way, you have the option to either download the latest stable release, or live on theedge by downloading the latest source code.

Note that Catel is primarily meant for Line of Business (LoB) applications


8/387

Catel uses unit tests to make sure that new updates do not break existing functionality.

Catel is very well documented. Every method and property has comments, and the comments are available in a separate reference helpfile. There is also a lot of documentation available, and in the future, in-depth articles will be written.

Catel is developed by a group of talented software developers, and is heavily under development. This is a great advantage because the

knowledge is not at just one person, but at a whole group. The developers of Catel all have more than three years of development

experience with WPF, and are using Catel in real life applications for at least 2 years.

Continue reading

Why Catel?Support for multiple platformsIntroduction to data objectsIntroduction to MVVMIntroduction to MVC

Why Catel?

We care a lot about the freedom you need as a software developer. Most frameworks require a developer to learn its conventions, or use thewhole framework or nothing at all. When we, the developers of Catel, use an external framework, we choose that framework for a specific reason,and don’t want to be bothered by all the other superb stuff it has to offer (maybe later, but not now).

During the development of Catel, we tried to maintain this freedom aspect which is very important to us. Therefore, all functionality is loosely

coupled. Sounds great, but everything is called loosely coupled nowadays. Catel contains a lot of different aspects, such as logging, diagnostics,

Reflection, MVVM, user controls, windows, etc. All these aspects are complementary to each other, but the great thing about Catel is that you

decide whether to use just one, some, or maybe all aspects.

As an example: you have a legacy application and want to use the DataWindow to write simple entry windows, but you are not ready for MVVM

yet. No problem, the DataWindow is complementary to MVVM, but does not require it. Therefore, you have all the freedom to use just what youneed, whenever you need it.

Most frameworks require a bootstrapper that completely decides how your application structure should look like. For example, your Views must

have this name, your controls must have that name. Again, in Catel, we wanted to give you the freedom you would expect from a framework.

The great thing about this freedom is that the different aspects of Catel can be used side-by-side with other frameworks, so you as a developer

can use the best framework for every aspect in your application.

Another nice thing is that Catel is WPF-based. Now you might be thinking: but hey, I use Silverlight! However, the upside of this approach is that

all goodies that are well known in WPF, but not in Silverlight are also brought to Silverlight. For example, in Silverlight there is no automatic

command re-evaluation. Catel does this out of the box, even in Silverlight.

Catel offers a solution in the following fields:

Data handling

MVVMAnd much more which you will find out during the use of Catel!

Support for multiple platforms

Catel is available on a lot of platforms.

Introducing "true PCL"XamlAndroid

iOSPlatform support by componentFundamental differences

For a list of caveats per platform, check out the following links:

Caveats in WPFCaveats in SilverlightCaveats in Windows PhoneCaveats in Windows RTCaveats in AndroidCaveats in iOS


9/387

Introducing "true PCL"

Portable Class Libraries (PCL) is a technique where developers can develop a single assembly that can be used by multiple platforms. Thereason the team decided not to use PCL is that it brings in too many limitations. We wanted to provide the developer all the possibilities of theplatform they are developing in, not the “least platform supported”.

As you can see in the diagram below, each platform has its own set of functionality (orange). When using PCL, the functionality will bedowngraded to the "least" platform (thus lots of features will be lost). Catel works the other way around by adding features of other platforms. Forexample, checking for dependency property changed is available on all platforms and works exactly the same for all platforms.

A great example of the advantages are the services that are provided by Catel. All the platforms that support some sort of GPS functionality havethe (which is an interface that is platform independent). Each platform (Windows Phone, WinRT, Xamarin, etc) have their ownILocationService implementation but the developer can use them in exactly the same manner without losing functionality. This means that instead of losing

functionality, Catel functionality by not using PCL but platform dependent assemblies instead.adds

Supported platforms

Xaml

WPF 4.0WPF 4.5Silverlight 5Windows Phone 8.0Windows Phone 8.1Windows RT 8.0Windows RT 8.1

Android

Android 4.0+ (Xamarin)

iOS

iOS 6.0+ (Xamarin)

Platform support by component


10/387

This page explains in detail what parts of Catel are available on specific platforms.

NET 4.0 NET 4.5 SL 5 WP 8.0 WP 8.1 WIN 8.0 WIN 8.1

Catel.Core

Catel.MVVM

Catel.MVC4

Catel.MVC5

Catel.Extensions.Controls

Catel.Extensions.CSLA

Catel.Extensions.Data

Catel.Extensions.DynamicObjects

Catel.Extensions.EntityFramework5

Catel.Extensions.EntityFramework6

Catel.Extensions.FluentValidation

Catel.Extensions.Interception

Catel.Extensions.Memento


11/387

Catel.Extensions.Prism

Fundamental differences

There are some fundamental differences between platforms (such as Xaml and Android). The table below explains the differences so it is easy tounderstand for a developer what to use when. Note that all services are defined by interfaces and can be used on all the platforms in the samemanner. The platform-specific implementations are hidden as much as possible to keep the view models very re-usable.

Feature Xaml Android iOS

Phone pages PhonePage or Page Activity TODO

Nested user controls UserControl Fragment TODO

Caveats in WPF

Below are all caveats in WPF.

Caveats in Silverlight

Below are all caveats in Silverlight.

Caveats in Windows Phone

Below are all caveats in Windows Phone.

Caveats in Windows RT

Below are all caveats in Windows RT.

Caveats in Android

Below are all caveats in Android.

Linker settings

Linker settings

When linking in release mode (or debug if you would like), the linker will remove all non-used items from the final application assembly. Since the

Know caveats? Feel free to add them!






12/387

binding system in Catel uses reflection, it might break when the linker is too aggressive when optimizing the app. To prevent optimalization, createa dummy file that uses the members of each type so the linker will not exclude them. Note that this class will never be instantiated, nor will i tsmethods be invoked. It is purely to let the static analysis be notified of the usage.

Below is an example class to force the inclusion of members in Android. For each type and its members, a method is added. Then each usedproperty is accessed and each used event is subscribed to.

public class LinkerInclude

{

public void IncludeActivity(Activity activity)

{

activity.Title = activity.Title = string.Empty;

}

public void IncludeButton(Button button)

{

button.Text = button.Text + string.Empty;

button.Click += (sender, e) => { };

}

public void IncludeEditText(EditText editText)

{

editText.Text = editText.Text + string.Empty;

editText.TextChanged += (sender, e) => { };

}

public void IncludeCommand(ICatelCommand command)

{

command.CanExecuteChanged += (sender, e) => { };

}

}

Caveats in iOS

Below are all caveats in iOS.

Introduction to data objects

It is very important to understand the data objects in Catel because they form the base pillar of all components used by the MVVM framework.

The ObservableObject classThe ModelBase classCreating your first data objectDeclaring properties

Simple propertiesProperties with property change callback

Adding validationSaving objects

Loading an objectSaving an object

Note that this applies to both properties and bindings



13/387

1.2.

The ObservableObject class

The ModelBase class

Creating your first data object

First of all, it is very important to realize that you shouldn't bore yourself with writing all the code below yourself. Catel contains lots of codesnippets that allow you to create data objects very easily in a short amount of time.

This example shows the simplest way to declare a data object using the class. By using a code snippet, the class is created in just 10ModelBase seconds.

Code snippets

model - Declares a data object based on the classModelBase

Steps

Create a new class file called .FirstModel.cs Inside the namespace, use the codesnippet and fill in the name of the class, in this case .model FirstModel

Code

This documentation is to be written in the future

This documentation is to be written in the future


14/387

///

/// FirstModel class which fully supports serialization, property changed

notifications,

/// backwards compatibility and error checking.

///

[Serializable]

public class FirstModel : ModelBase

{

#region Fields

#endregion

#region Constructors

///

/// Initializes a new object from scratch.

///

public FirstModel()

{ }

///

/// Initializes a new object based on .

///

/// that contains the

information.

///

/// .

protected FirstModel(SerializationInfo info, StreamingContext context)

: base(info, context) { }

#endregion

#region Properties

// TODO: Define your custom properties here using the propdata code snippet

#endregion

#region Methods

///

/// Validates the field values of this object. Override this method to enable

/// validation of field values.

///

/// The validation results, add additional results

to this list.

protected override void ValidateFields(List

validationResults)

{

}

///



///

/// The validation results, add additional results

to this list.

protected override void ValidateBusinessRules(List

validationResults)

{

}

#endregion

}


15/387

1.2.

1.2.

Declaring properties

The next step to learn on the class is how to declare properties. There are several types of properties, and they will all be handled inModelBase this part of the documentation.

The class uses a dependency property a-like notation of properties.ModelBase

Simple properties

This example shows how to declare the simplest property. In this example, a string property with a default value will be declared with the use of acode snippet.

Code snippets

modelprop - Declares a simple property on a model

Steps

Open created in the previous step.FirstModel.cs In the Properties region, use the code snippet , and use the following values:modelprop

Code snippet item Value

description Gets or sets the simple property

type string

name SimpleProperty

defaultvalue "Simple property"

Code

///

/// Gets or sets the simple property.

///

public string SimpleProperty

{

get { return GetValue(SimplePropertyProperty); }

set { SetValue(SimplePropertyProperty, value); }

}

///

/// Register the SimpleProperty property so it is known in the class.

///

public static readonly PropertyDataSimplePropertyProperty =

RegisterProperty("SimpleProperty", typeof(string), "Simple property");

Properties with property change callback

Code snippets

modelpropchanged - Declares a simple property on a model with a property changed callback

Steps

Open created in the previous step.FirstModel.cs In the Properties region, use the code snippet , and use the following values:modelpropchanged


description Gets or sets the callback property

type string


16/387

name CallbackProperty

defaultvalue "Callback property"

Code

///

/// Gets or sets the callback property.

///

public string CallbackProperty

{

get { return GetValue(CallbackPropertyProperty); }

set { SetValue(CallbackPropertyProperty, value); }

}

///

/// Register the CallbackProperty property so it is known in the class.

///

public static readonly PropertyDataCallbackPropertyProperty =

RegisterProperty("CallbackProperty", typeof(string), "Callback property",

(sender, e) => ((FirstDataObject)sender).OnCallbackPropertyChanged());

///

/// Called when the CallbackProperty property has changed.

///

private void OnCallbackPropertyChanged()

{

// TODO: Implement logic

}

Adding validation

It is very easy to add validation to a class (both the and ). There are several ways, but this getting started guide willModelBase ViewModelBase

handle only the most simple one.

To enable validation, you must override at least one of the following methods:


17/387

1.2.3.

///



///

/// The validation results, add additional results to

this list.

protected override void ValidateFields(List validationResults)

{ if (string.IsNullOrEmpty(FirstName))

{

validationResults.Add(FieldValidationResult.CreateError(FirstNameProperty,

"First name cannot be empty"));

}

}

///



///

/// The validation results, add additional results to

this list.protected override void ValidateBusinessRules(List

validationResults)

{

if (SomeBusinessErrorOccurs)

{

validationResults.Add(BusinessRuleValidationResult.CreateError("A business

error occurred"));

}

}

After the validation is implemented into the object, the validation will occur every time a property on the object changes. It is also possible to

manually validate by calling the Validate method.

There are also other ways to add validation to a data object:

Validation via data annotations - attributes such as the RequiredAttribute

Validation via - custom validation such asIValidator FluentValidation

The great thing is that Catel will gather all validation results from all different mappings and combine these into the . This contextValidationContext can be used to query all sorts of validation info about an object.

Saving objects

Saving and loading objects out of the box has never been so easy. can automatically save/load objects in several ways, suchSavableModelBase as memory, file in different modes (binary and XML). This example shows that making your objects savable is very easy and does not take anytime!

Code snippets

model - Declare a model based on the classModelBase modelprop - Declare a simple property on a model

Steps

Create a new class file called .Person.cs Inside the namespace, use the codesnippet and fill in the name of the class, in this case .model Person Change the base class from to .ModelBase SavableModelBase

Note that this is just an introduction, more information about validation can be found in other parts of the documentation


18/387

4. In the Properties region, use the code snippet , and use the following values:modelprop


description Gets or sets the name

type string

name Name

defaultvalue "MyName"

Code


19/387

///

/// Person class which fully supports serialization, property changed notifications,

/// backwards compatibility and error checking.

///

[Serializable]

public class Person : SavableModelBase

{

#region Fields #endregion


///

/// Initializes a new object from scratch.

///

public Person()

{ }

///

/// Initializes a new object based on .

///

/// that contains the information.

///

/// .

protected Person(SerializationInfo info, StreamingContext context)

: base(info, context) { }

#endregion

#region Properties

///

/// Gets or sets the name.

///

public string Name {

get { return GetValue(NameProperty); }

set { SetValue(NameProperty, value); }

}

///

/// Register the Name property so it is known in the class.

///

public static readonly PropertyData NameProperty = RegisterProperty("Name",

typeof(string), "MyName");

#endregion

#region Methods

#endregion}

Loading an object

Loading an object is really simple once the class has been created. It is important to use the static method on the class:

var person = Person.Load(@"c:\person.dob");


20/387

Saving an object

To save an object, an instance is required. Then simply call the method.Save

var person = new Person();

person.Name = "John Doe";

person.Save(@"c:\person.dob");

Introduction to MVVM

This part gives an introduction to MVVM in Catel.

MVVM framework comparison sheetDifferent interpretations of MVVMValidation in model or view model?Introduction to MVVM and modelsCreating view models with CatelIntroduction to servicesIntroduction to the nested user controls problemIntroduction to unit testing in MVVM

MVVM framework comparison sheet

In this MVVM framework comparison sheet includes as many aspects as possible. However, it might be possible that some were missed. If youhave features that are not included in the comparison sheet, or you find that information is incorrect, please let us know!

Below is short list of definitions:

Definition Explanation

VM View-Model

Frameworks reviewed

Framework Description Website

Catel Catel is more than just an MVVM toolkit. It also includes user controls and lots ofenterprise library classes. The MVVM toolkit differs itself from other frameworks ofthe simplicity and solves the "nested user control" problem with dynamic viewmodelsfor user controls

http://catel.codeplex.com

Caliburn.Micro A small, yet powerful implementation of Caliburn designed for WPF, Silverlight andWP7. The framework implements a variety of UI patterns for solving real-worldproblems. Patterns that are enabled include MVC, MVP, Presentation Model(MVVM), and Application Controller.

http://caliburnmicro.codeplex.com

Cinch (V2) Cinch is a MVVM framework that exposes a number of helper classes to allow thedeveloper to quickly get to grips with creating scalable testable MVVM frameworksas quickly as possible.

http://cinch.codeplex.com

MVVM light The MVVM Light Toolkit is a set of components helping people to get started in theModel - View - ViewModel pattern in Silverlight and WPF. It is a light and pragmaticframework that contains only the essential components needed.

http://mvvmlight.codeplex.com

This comparison sheet is last updated on September 4th, 2012

http://catel.codeplex.com/http://caliburnmicro.codeplex.com/http://cinch.codeplex.com/http://mvvmlight.codeplex.com/http://mvvmlight.codeplex.com/http://cinch.codeplex.com/http://caliburnmicro.codeplex.com/http://catel.codeplex.com/


21/387

Simple MVVMtoolkit

Simple MVVM Toolkit makes it easier to develop Silverlight, WPF and WP7applications using the Model-View-ViewModel design pattern. The purpose of thetoolkit is to provide a simple framework and set of tools for getting up to speedquickly with applications based on the MVVM design pattern. The emphasis is onsimplicity, but it contains everything you need to implement MVVM for real-world lineof business applications.

http://simplemvvmtoolkit.codeplex.com/

WAF The WPF Application Framework (WAF) is a lightweight Framework that helps youto create well structured WPF Applications. It supports you in applying a LayeredArchitecture and the Model-View-ViewModel (aka MVVM, M-V-VM,

PresentationModel) pattern.

http://waf.codeplex.com/

Platform support

Catel Caliburn.Micro Cinch (V2) MVVM light Simple MVVM WAF

WPF

Silverlight 4

Silverlight 5

Windows Phone 7

Windows Phone 8

WinRT

Available via NuGet

UI features


MVVM specific window

MVVM specific user control

Dynamic view model injection

Lazy loading of view models

View to VM communication via attributes

Events when views are actually loaded

ViewModelBase functionality


INotifyPropertyChanged

IDataErrorInfo

IDataWarningInfo

Support for canceling data

Support for confirming data

Automatic property definitions

Automatic model communications (mappings)

Generate features

http://simplemvvmtoolkit.codeplex.com/http://waf.codeplex.com/http://waf.codeplex.com/http://simplemvvmtoolkit.codeplex.com/


22/387


Communication with other VM via messenger

Communication with other VM via attributes

RelayCommand / DelegateCommand

EventToCommand trigger

IoC container support

Unity support

MEF support

Background task manager

ViewModelManager with live VM instances

Project and item templates

Design time example data support

Memento pattern

View model services


IMessage(Box)Service

INavigationService

IOpenFileService

IPleaseWaitService

IProcessService

ISaveFileService

IUIVisualizerservice

Unit test versions of services

Windows Phone specific view model services


IAccelerometerService

ICameraService

ICompassService

IGyroscopeService

ILocationService

INavigationService

IVibrateService

Different interpretations of MVVM

There are two different interpretations of MVVM, the "purist" way where the model is protected, or the "shortcut" way where the view model onlyprovides the instance of the model and the view then binds directly to the model.


23/387

Shortcut interpretation

This is what most people do. The view model once implements the model, and then provides the model to the view. The view then

Advantages

Easy to use

Fast since view model hardly contains any properties

Disadvantages

Always need to bind to Model.[PropertyName], but for view model properties it's just [PropertyName], might be confusingLess control over validation (you cannot insert logic between View Model where MVVM is all about

Purist interpretation

This is what the developers of Catel strongly believe in. It requires a bit more code, but gives great freedom and control and protection of the

model because all bindings go through the view model.

Advantages

Full contol and freedom, you can inject both logic and validation between view and model (what MVVM is actually about)

Everything is available on the view model, no need for "sub-bindings" (such as Model.[PropertyName])

Protection of your model from the view

Disadvantages

Needs a bit more code (but thanks to code snippets and the Expose attribute, this is not a big disadvantage)

Validation in model or view model?

I have had lots of discussion whether the validation should take place in the model or the view model. Some people think that the validationshould always occur inside the model because you don’t want to persist invalid models to the persistence store. Others say that the models itselfdon’t need validation, but the state the view model is in requires the validation. I think both are true, and I will tell you why.

First of all, you don’t want invalid models in your persistence store. Thus, the most basic checks such as type, ranges and required fields should

be validated in the model. But sometimes, it is required to restrict the user more than the model does, and that’s where validation in the view


24/387

model comes in handy. Another reason why you want to implement (a part of) the validation in the view model is the state of the model inside a

workflow. If you have a workflow that updates the model step by step, the model isn’t valid after the first step in the workflow. However, you

already want to persist the model because the user might decide to execute the following steps at a later time. You don’t want to implement the

state logic of a workflow in your model (and if you did that, get rid of it, as soon as possible). This is another feature where the view model

validation comes in handy.

The good news is that with Catel, it doesn’t matter what you want, because it’s all possible. If you want your model to do all the validation, then

this is possible using the Model and ViewModelToModel attributes which map the values of the properties and the errors directly to the model sothe view model acts as a proxy between the view and the model. If you want to do all of the validation inside the view model, then you canimplement the ValidateFields and ValidateBusinessRules methods in the view model. And, if you want the best of both worlds, such as me, thanyou can use a combination of the techniques described above.

Introduction to MVVM and models

This part of the documentation will explain all the parts of MVVM, in the order in which we think they must be built. First of all, the Models, whichare the closest to the business. Then, the View Models which define what part of the Models should be visible to the user in a specific situation.This also includes validation that is specific for the functionality that the View Model represents. Last, but not least, the View itself, which is thefinal representation of the View Model to the end-user.

As you will notice (or maybe you don't), this framework has a lot in common with other MVVM frameworks out there. This is normal because all of

the frameworks are trying to implement the same pattern, which isn't that hard to understand if you think about it long enough. Before we started

writing the MVVM framework, we first investigated other frameworks because there already are enough, probably too many. However, even the

better (or best) still took too much time to use, and there was too much code we had to write to create a View Model. That's the point where we

decided to write our own framework that contains lots of luxury for lazy developers such as us.

Models

The Models part is one of the three major parts of MVVM. Therefore, I want to tell you a bit about what kind of Models we use to store our data.Basically, you can use all types of objects as Models, as long as the Models implement the most commonly used interfaces required by WPF orSilverlight.

For MVVM, it is very important that the following interfaces are implemented:

INotifyPropertyChanged

If this interface is not implemented, changes will not be reflected to the UI via bindings. In other words, your Model and View Model willbe useless in an MVVM setting.

Finally, it is strongly recommended to have your Models implement the following interfaces as well:

IDataErrorInfo

If this interface is not implemented, errors cannot be shown to the user.IEditableObjectIf this interface is not implemented, a Model cannot work with “states”. This means that a user cannot start editing an object and finallycancel it (because there is no stored “state” that can be used to restore the values).

View Models

View models are the classes that contain the view logic. They can be seen as a container for all models in a specific view, including the behaviorto interact with these models (for example adding or removing them from a collection). It is very important that a view model also implements the I

interfaces just like the models do.NotifyPropertyChanged

Creating view models with Catel

The View Models in Catel are very easy to write, and give the end-user a great flexibility in how to approach the Models. This part of the article willexplain the classes that make it possible to easily create View Models.

The class is the most important class of all in the MVVM Framework of Catel. Of course, it can't do anything useful without theViewModelBase other classes, but all the View Models that are created using Catel derive of this class. is based on the class thatViewModelBase ModelBase ships with Catel. Thanks to the existence of that class, the MVVM framework was set up very quickly (although “very quickly” is relative). Below isa class diagram that shows the class tree:


25/387

The class diagram above shows how many default interfaces of the .NET Framework are supported in the class. Since most of theseModelBase interfaces are used by WPF as well, the class itself can take huge advantage of the implementation of .ViewModelBase ModelBase

Because derives from , you can declare properties exactly the same way. Even better, you can simply useViewModelBase ModelBase ModelBas (or the extended ) to create (and save) your Models, and use as the base for all the View Models.e SavableModelBase ViewModelBase

Creating a view model

To declare a View Model, use the following code snippet:

vm - defines a new view model

When using the code snippet, this is the result:vm


26/387

///

/// $name$ view model.

///

public class $name$ViewModel : ViewModelBase

{

#region Fields

#endregion


///

/// Initializes a new instance of the class.

///

public $name$ViewModel ()

{

}

#endregion

#region Properties

///

/// Gets the title of the view model.

/// /// The title.

public override string Title { get { return "View model title"; } }

// TODO: Register models with the vmpropmodel codesnippet

// TODO: Register view model properties with the vmprop or vmpropviewmodeltomodel

codesnippets

#endregion

#region Commands

// TODO: Register commands with the vmcommand or vmcommandwithcanexecute

codesnippets

#endregion

#region Methods

#endregion

}

Declaring properties

There are several code snippets available to create View Model properties:

vmprop - Defines a simple View Model property.vmpropmodel - Defines a View Model property with . The property is also made private by default.ModelAttribute vmpropviewmodeltomodel - Defines a View Model property with .ViewModelToModelAttribute

When using the code snippet, this is the result:vmprop

Note that declaring properties works exactly the same as declaring properties for the ModelBase


27/387

///

/// Gets or sets the name.

///

public string Name

{

get { return GetValue(NameProperty); }

set { SetValue(NameProperty, value); }

}

///

/// Register the Name property so it is known in the class.

///

public static readonly PropertyData NameProperty = RegisterProperty("Name",

typeof(string));

In the View, it is now possible to bind to the property of the View Model, as long as is set to an instance of the View Model.Name DataContext

Declaring commands

There are several code snippets available to create View Model commands:

vmcommand - Defines a command that is always executable.

vmcommandwithcanexecute - Defines a command that implements a method to determine whether the command can beCanExecute invoked on the View Model in its current state.

When using the code snippet, this is the result:vmcommandwithcanexecute

///

/// Gets the Add command.

///

pu

catel.4.2.0.documentation_

Documents

Transcript of catel.4.2.0.documentation_