#insideioapps

On the last posts I talked about the general architecture and how we handle the app boot process, today we will dig into the different components that we have, what are their responsibilities and how they work and communicate with each other.

We have four main components: View, ViewModel, Controller and Model (App & Platform Services).  

View                    

The view component is mostly composed of Views, XAML (AXML, HTML, etc) and code behind.  It also contains the usual custom UI controls, app resources and basically everything that is seen by the user. Our views have also two extra responsibilities, besides showing and animating content, they must show to the user when an operation is running and display them error messages when it fails. To achieve this, each of our ViewModels has some INotifyPropertyChanged (INPC) properties which the view binds. We simplified the process by using a base class for all views that handles these data bindings and shows the user the error and loading messages.

Our views aren’t restricted to a single ViewModel, this means that a single View can use all the ViewModels available or none if that is the case (usually only the splashcreen view). Of course a view that consumes multiple ViewModels information must have a main ViewModel so that it can fulfill the responsibilities enumerated before. With this approach we avoid similar or exact representation of data and operations, meaning that each ViewModel is a container of only the relevant data and operations to its purpose, completely unaware where and who is consuming/calling his data/operations.

This approach of having fine grained ViewModels is a little hard to implement when you are developing an app that is targeting tablets before phones, simply because on the tablets you usually show a lot more info in a single view than on a phone, but when starting from the phone it enables you to develop the tablet version very quickly since everything is well divided and organized. When you are targeting both tablet and phone, you can just do the phone version first and then make the tablet version, but regardless the order, of the versions development, there will always be refactoring. The golden rule is to not be afraid to move things around and aggregate related operations in a common place, even if there are a lot of things to change. The truth is, if you duplicated something once you are probably going to do it again in the future. Finally, if your tablet version needs more functionality that you didn’t have on the phone you can just add it on a specific ViewModel, or create another if none of the existing fits the new data/operation. Some good reads for thinking ahead and dividing code is the Open-Closed principle and the Single Responsibility principle .

Small Components

 We have a bunch of smaller, but not less important, components that I would like to introduce before continuing with the main ones, these components are basically the glue between the main components and the user.

Exception Handler                          

What is the worst thing that can happen to your app when someone is using it? A crash! Besides being annoying it will certainly generate a lot of bad reviews on the market. You should never let your app crash for code that you control! How? Try/catch everything! Even if you don’t do anything with that exception (at least always log them). When I said code that you control I meant everything from the views down, ViewModels, Controllers and Model. The app will still crash for “god only knows” reasons like platform errors (no one is perfect), some UI graphics library that you are using, etc. For this uncalled exceptions we usually let them crash the app but always log them, on some of our apps we save the error and ask the user on the next opening if they want to send it to us or if you can (and previously asked user permission) just send it to an analytics service.

On our apps almost all operations start with some user interaction that will call a ViewModel command, which eventually will call a service or a controller. As you would guess our ViewModels are where we catch exceptions, to demonstrate how, the following snippet shows one of our commands implementation.

So you were probably expecting to see some try catch or some RelayCommand implementation but no, our commands result on the return of a method called CreateCommandForUserAction, that in this case has two parameters a Func<Task> and a string. The func parameter is the implementation of the command, the logic that we want to run, and the other parameter I will get to that soon. The CreateCommandForUserAction ends up creating a command that wraps everything around a method called LoadingSafeRun, this one besides calling the func inside a try catch block, it also handles the exceptions by invoking our ExceptionHandlerService.

The ExceptionHandlerService is a very simple and bare exception handler, it basically is a hashtable<exception,handler>, and his handlers are usually just routines that returns some string given a specific exception like:

In some rare cases the handler does more than returning a string but usually the ExceptionHandlerService only delivers error strings so that the user can know what went wrong.

Before going into the next small component, here you have the implementation of the LoadingSafeRun routine.

Reporting errors and ongoing operations

As a user I like to know what is going on, especially when I’m on my phone with only one app taking the entire screen, loading and error reporting ensures me that the app is actually doing something or that it failed for some reason. (As a developer I always try to deliver the experience that I would like to have.) Remember that second parameter on the CreateCommandForUserAction? It is the loading string that will appear to the user.

Looking back to the LoadingSafeRun routine you can see exactly how we handle this reporting, the loading operations like I said consist on INPC properties that views bind to, so reporting a loading operation is just setting a string in a property. The error reporting is actually divided in two ways, depending if the action was started by the user or not. If it was started by the user we show the error on a message box (dialog on android) so that the user can have a “strong” visual representation that something went wrong. If the operation wasn’t started by the user we only show some small visual representation, on WindowsPhone we show the error message on the system tray on android we show a quick toast notification.

Navigation

Any app (any real one at least) has some kind of navigation, this navigation can be to some view/control/etc inside the app our to some other app or platform feature. In our apps our navigation consists on in-app view change. The external navigation we usually wrap around a service like IMailService or IPhoneCallService since this kind of navigation usually needs the app to go to background causing it to be deactivated or something similar.

The internal navigation is also a service, a custom app service (platform specific), that knows how to navigate to other views, show popups, show flyouts (on Windows 8), etc. By having a per platform service we can take advantage of all the platform navigation features and also maintain our code portability.

We have two types of navigation, the navigation that needs some kind of data to be passed along and the plain old navigation that doesn’t need any data exchange at all. To exchange data between viewmodels we use a Messenger . Our app service always has two ways of switching between views, you have a command interface and a method interface. The command interface is strictly used by the views, as an example, on windows phone it’s not uncommon to see a button command directly binded with a navigation command, this is useful because there are some views that a user can navigate for a couple of places inside the app, and to avoid having a custom command in 3 or 4 different view models, we simply “publish” the navigation service instance and let the views handle that. Of course this can be problematic since we are delegating to the view one of the app core responsibilities but by doing this you avoid identical code on multiple view models and make everything smoother and understandable on both view models and views.

The other type of navigation has some data contract that needs to be fulfilled before any navigation can be done, we are thinking on adding this data contract directly to the app navigation service because of pure convenience, but for now we still role with this model.

Finally the other components of our app usually don’t have any access to the navigation at all. One rare case is when the exception handler needs to navigate to some view after an error, for instance our FB Pages Manager has a handler hooked up for when the facebook session expires, and when it does the handler sends the user to the login view.

Wrap Up

Our apps have many components, today we explained the ones that really matter, the components that the user actually see and interact. A few tips

Avoid at all costs an app crash, it’s definitely one of the worst things that can happen.

Always report to your user what your app is doing, take special attention to when the operations was started due to user interaction.

Try to tell the users when something goes wrong, why it failed, this will prevent a bunch of email telling you that your app doesn't work.

Last time we outlined the basic architecture of our apps as well as how we made the app lifecycle management as portables as we could, today we continue with the lifecycle topic, but this time we explain how we manage and divide our data.

Data Management

Our apps have two types of data, the persistent data, saved when the app is closed or deactivated (pressed the menu button, incoming call, etc), and transient data, saved only when the app is deactivated (and restored when activated). This last one usually serves to restore a previous view state in case that the app memory gets collected by the system. The data is also in two different components, the persistent data is stored by the controllers and the transient by the ViewModels. This means that the controllers and ViewModels have to know which data they need to store and how to do it, for that we have one interface for the controllers and some abstract methods on our AppViewModelBase:

 All the controllers that need to save data have to implement the IDataController interface, all the ViewModels must extend the AppViewModelBase. Although they have basically the same goal, their contracts are very different for a reason, the controllers load and save operations are asynchronous because of the potential size of the data and in the closing/launching states of an app, there are usually a number of things that need to be done, so running them in parallel can improve the app load/close time. The ViewModel load/save are blocking operations, this is also for quicker app activation time, this methods run on the UI thread, to avoid any thread/task context switch, and we’re ok with that because, since there is really nothing to show until the ViewModels load back their transient data, we can take some time.

So we explained how we load and store our data but who starts this process? We’ve already told you that the controllers load/save operations are called directly by the AppManager, on the initialize/activated for the load and closed/deactivated for the save. In the ViewModels we have another entity, the ViewModelManager (previously the ViewModelLocator). For the people that aren’t used to MVVM Light toolkit, the ViewModelLocator is basically a “proxy” to all ViewModel instances, what we’ve done was give it the responsibility to also handle the viewmodel load and save state. So the AppManager calls the ViewModelManager on the activated and deactivated methods to load and save their state respectively. To help summarize all of this, here is an image of our apps lifecycle:

App lifecycle

Wrap Up

Apps are just a mesh of services and data, standardizing the way you handle your data is important to its stability, scaling and overall performance. A few tips:

Segment your data, you can use a model like ours where there is a persisted data and a transient one, but there are more ways to do so.

Be very aware, where and when your data is going to be loaded/stored, this can help you track bottlenecks and will definitely give you more control.

Go async, there are many advantages and disadvantages of doing so, but Microsoft recent SDK releases clearly states that the future is async.

In the last post I talked about the folder structure and project organization, today we start explaining our building blocks, which are the services, modules and processes that we use on every app. Our apps can be divided in four major components: Views, ViewModels, Controllers and Services. We’ve named every component that is not directly related to the app goal (e.g. how to take photos) as Platform Services and every component that is related (e.g. how to consume some service API) as App Services. Usually the Platform Services are placed on a separated library (in our case the IOToolkit) so that we can reuse them on other apps. Visually our apps can be represented by the following image.

Figure 1- Our (pseudo) architecture

Looking at the image you can check that it’s just MVVM with something extra, which we call controllers. This controllers exist only to remove some of the ViewModel responsibilities, like assessing the business layer (on the classic 3 layers. The Platform Services consist on the contracts (interfaces) and implementation of platform specific operations, as an example, we have an IPhotoService to take photos and an ICryptoService that makes MD5 hashes, etc. The App Service has the app related services, on CloudMesh it has the cloud service clients (or agents). Finally, we have the PCL and Platform Framework that self-explanatory (and probably shouldn’t be in an architecture image) but I wanted to highlight that although Platform Services and App Services consist on mostly Portable code, in some cases they need to have platform specific code.

Our objective, with this architecture, is to make everything as portable as it can be, all our ViewModels and controllers are 100% portable, our app services can sometimes have 1 or 2 elements that aren’t portable and our platform services have both portable (inside the respective frameworks, Windows and Xamarin) and non-portable code. By decision, all our views are platform specific even with libraries like Xamarin.Forms out there, the reasons are simple, more control and (easy & quick) customization.

To fulfill the portability goal we rely on interface based programming, inversion of control and dependency injection. This means that almost all our code is implementing some interface (this does not include Views, ViewModels and Controllers), the object lifecycle is managed by our dependency injector (excluding the Views) and all of our objects are instantiated by the dependency injector (again excluding the Views, and some other specific cases). The reason why we don’t manage the views lifecycle is, on Windows Apps the framework manages it, on android  we can manage the activity/fragments as we want and on iOS you can decide if you want to manage them or not.

We chose not to create contracts for ViewModels and Controllers because they are supposed to be the core of the application and shouldn’t be (directly) dependent on any platform specific features, although they consume most of the services, portable or not.

The instantiation process usually starts on the boot phase of the app, there is one “god” class (AppManager) that handles all the injector configuration, early navigation and controller loading. You can check the generic flow on the following picture.

App Lifecycle

Figure 2 - App Initialization

The application boot process is something that we are always trying to improve, in our newest version the AppManager handles all the app lifecycle, from start to finish, as well as the initial navigation. The pre initialization routine was made to (quickly) configure some platform specific information, as an example, on windows phone we use this to set a custom accent color or/and change the default theme. The app initialization is divided in 3 steps, the first (platform setup) is the one responsible to configure the dependency injector and other platform related services (e.g. NavigationService), the services initialization is optional, we usually use it for things like changing the current app language (when we have the option, inside the app, to switch the language) and finally the controller initialization loads any persistent data.

This is not a strict flow, on windows phone the pre initialization is called inside the Launching event handler and the rest is done on a SplashScreen view, on android all of these steps are called on the OnCreate of our launching activity.

There are three other methods, on the AppManager, to handle the rest of the app lifecycle: the Deactivated, Activated and Closing. Each of those methods are called on different places depending on the platform they are running, on Windows Phone they are called on the respective event handlers, on android we call the Deactivated on the OnSaveInstanceState, the Closing is called on the OnStop depending whether the OnSaveInstanceState was called or not, the Activated can be called on the OnRestoreInstanceState[JS1] , if the system preserved the app memory, or on the OnCreate depending if there is a bundle, or not, present.

This is the current system that we have, I’m sure that as we further develop android apps or go into iOS, some of these things will be changed and improved.

Wrap Up

With the rise of portable class libraries and platforms like Xamarin, making portable (but “native”) apps just got easier, but still a good deal of discipline is needed to really make the apps portable. A few tips:

Separate app related code from non app related code.

Use interface based programming to make your app core fully portable.

Separate your framework code from your app on a different library to reuse it.

Use libraries like Xamarin.Mobile that already combines in one api common platform services.

Understanding each of the platforms lifecycle is very important, only then you can create some common (and therefore portable) handling to each of its states.

For the last three years I’ve been developing apps for Windows Phone/Windows 8.1. In the beginning it was just for fun, and also an attempt to understand the app ecosystem and the technology involved, very soon I figured out that making app is much more than coding. Everything you do in an app, starting with code organization, all the way to how you talk with users, is critical to an app success. This is my way to contribute to the community that has helped me in the last 3 years, I’ll try to share all the technical and non-technical knowledge that I’ve acquired by building apps.

In this post I’m going to talk about how we, at ImaginationOverflow, structure our app folder and project, the idea is to explain why and where we store our code and resources, how we organize them on a Visual Studio Solution and on the common file explorer

Folder Structure

How should we organize our assets on the file system? You can follow any project directory layout like Maven, or any other found on the web, or just organize the resources as you need them; at ImaginationOverflow we divide the app development process into three iterative phases: design, development and production. The goal here is whenever you are working on one of those phases you quickly get to the target folder where the related resources are. With this we get to the three root folders of our projects Design, Code (or Source) and Production. We’ve also added another root folder named External, where we store all the third party libraries, in both deliverable or source code form. Although it may sound strange to store some open-source library code, we primarily do it when we change the source to simplify the app integration, or correct bugs, but it can be a safe guard when for some unknown reason the source vanishes. Most recently we started to fork the projects, removing the libraries source from the apps repository, this reduces the amount of code you have to manage on the app repository and makes it easier to share custom changes between apps and pushing bug fixes to the original repository.

The Design folder is where we store all images, vectors, psds (Photoshop Project Files) and other design related stuff; we don’t really have an organization convention for this one, when we use a designer this folder is merely a soft link to the dropbox/onedrive/etc folder. Please note that having all your visual resources stored is really important, from the main app icon (tile) to those little ones scattered though the app. When we design some icon/image we always try to make it much bigger than the actual production size, as an example we make our tiles 4000x4000 pixels, we do this so we only have to scale down our resources which, although it reduces some details it’s better than the alternative of scaling up, scale up makes everything blurry and ugly. We use the same approach for icons and other visual resources, always get the biggest possible or preferably the vector file that “always” scales perfectly.

The Code folder has all the code we produced for an app; it usually contains the Visual Studio solution file(s) (.sln), a folder named Common (or Portable) where all our Portable Class Libraries (PCL) projects are stored and a folder for each supported platform. For example we have one upcoming app that will be available for Windows Phone, Android and iOS, so we have a folder for each platform. This folders store the platform specific projects making everything organized and easy to follow.

We add a lot more stuff to the code folder, as an example, if the app has a website we usually add to the Code folder a separate .sln and a Web folder, if we do unit tests we create a Test folder and so on.

The Production folder is where we store all the app deliverables (xaps, apks, etc), the store descriptions, the images, store kits and other production related resources. Usually it has 4 subfolders:

Deliverables – where we store all public and beta xaps, usually has one subfolder for each public version with the respective deliverable plus a beta subfolder where again we have a subfolder for each version with its file.

Descriptions – containing all the localized app descriptions and keywords.

Screenshots – where we store all localized screenshots, usually contains a subfolder for each supported language.

Misc – random place to store production related stuff, like in app purchases images and descriptions, press kits, ad banners, etc.

When we have more than one platform, we replicate the structure we use on the Code folder, creating a platform specific subfolder under Screenshots and Deliverables.

To wrap up this section here is an example of our folder structure:

root                 —- code ———  Common ———  Windows ———  WindowsPhone ———  SomeOtherPlatform ———  MyApp.sln ———  MyApp.Web.sln —- design —- external ———  code ———  deliverables —- production ———  deliverables ————-       v1.0.0.0 ————-       v1.1.0.0 ———  descriptions ————-       en-en.txt ————-       pt-pt.txt ———  screenshots ————-       pt-pt ————-       en-en ———  misc ————-       in app purchases ————-       press kits

Project Structure

The windows app ecosystem runs over an architectural pattern named Model View ViewModel (MVVM), to describe it in a few words we could say that the View represents your app user interface, on Windows Apps this means your xaml and some, view related, code behind (e.g. animations). The ViewModel is where your “showable“ data is placed and where your behaviors (e.g. button clicks) are implemented, and finally the Model is everything else that your app needs to do, that is not directly related to what your user is seeing or clicking (e.g. getting data from a service).

On our apps we added a new component that we call “Controller”, they simply are an extra layer to divide some of the ViewModel responsibilities, but we will talk about our components on a future post.

Every app that we have starts with the following platform specific projects:

App.[Platform] – the View from MVVM contains all the user interface and related resources.

App.Configurator – the project where we configure our injector with all platform specific services. (We rely on dependency injection to instantiate almost all our objects)

App.Services – a project for platform specific code (only created when necessary).

And the following PCL projects:

App.Common – where app specific services are declared, usually it contains the interfaces for In App Purchases (iap), navigation service, app specific services, etc.

App.Configurator – where we add configure the injector with portable services.

App.Controllers – where all the controllers are defined and implemented.

App.Controllers.Data – data classes used by the controllers and ViewModels.

App.Localisation – where all the string resources are stored (resx files).

App.Storage – where the app storage services are implemented and defined.

App.ViewModels – where the MVVM ViewModels are implemented.

Our MVVM Model is an undefined collection of other PCL projects, for instance CloudMesh model consists of 13 projects (at this moment), one for the service contracts, another for service data classes and the other 11 are for each of the cloud services we support.

Since each project has a strict set of responsibilities it makes knowing where things are, and where to put them, easy to find and having this division also helps to avoid circular references.

This model also has some disadvantages, the most critical in my opinion is: as the project number grows the build time gets slower, this is a huge issue especially when you are between debug sessions, long build times can make you lose focus and be less productive [FIND LINK FOR THIS].

I will go no further on the Project Structure since my next post will explain how this all comes together.

Wrap Up

The golden rule on folder organization is simple, organize it the way you can access what you want in the quickest and easiest way possible, while maintaining some kind of structure. Having a folder like the Production one, which has all the store assets and descriptions organized, is an easy way to reduce errors on publishing and it also boosts the app submission time, especially when your apps support multiple languages. Try to save your app deliverables, although we always beta test our apps (and updates) remember that there can always be a critical bug that goes live to the public, so saving your previous distributables is always a safe guard against this, as it allows you to just downgrade the app. Another good practice is creating a branch/tag (depending on your version control system) for each app update, this way instead of having only the XAP you also have the source..