Microsoft Dynamics AX

Windows 8 App Starter Kit

App Development Guide Version 1.0
Table of Contents
Microsoft Dynamics AX Windows 8 App Starter Kit ..................................................................................... 1
App Development Guide Version 1.0 ....................................................................................................... 1
1. Introduction ...................................................................................................................................... 3
2. Building your first Dynamics AX App for Windows 8 ........................................................................ 3
2.1. Step 1 – Decide what your app is great at .................................................................................... 3
2.2. Step 2 – Decide what user activities to support ........................................................................... 4
2.3. Step 3 - Decide what features to include ...................................................................................... 4
3. Development - Building a simple window 8 app that integrates with Dynamics AX 2012 R2.......... 5
3.1 Step 1- Prepare an AIF service in Dynamics AX 2012.......................................................................... 5
3.2 Step 2- Create a new Windows Store App Project in Visual Studio 2012 ......................................... 13
3.3 Step 3- Configure the Package.appxmanifest ................................................................................... 14
3.4 Step 4- Create a Service Reference to a Dynamics AX AIF Service ................................................... 16
3.5 Step 5- Consume data from Dynamics AX within a Windows 8 App ................................................ 17
3.6 Step 6- Present data from Dynamics AX within a Windows 8 App ................................................... 19
4. Using Blend to enhance the UX of your Windows 8 App................................................................ 23
5. Conclusion ....................................................................................................................................... 26

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 2 OF 26

1. Introduction

Before you get started on building your first Dynamics AX app for Windows 8, you will need to setup
your development environment.

Development environment requirements:

 Windows 8
 Visual Studio Express 2012 and Blend for Visual Studio
 Dynamics AX 2012

In addition to development tools, a developer license is required to develop and test Windows Store
apps. The license is free and Visual studio will walk you through the process of getting a license.
More information about developer licenses can be found here.

2. Building your first Dynamics AX App for Windows 8

For this guide we will be following the plan and design steps provided in the Windows Store Apps
Dev Center.

Before we get started on developing our Dynamics AX app for Windows 8, we must first do some
planning. For our first app we will build a companion app that allows Dynamics AX users to take
action on Work list notifications.

2.1. Step 1 – Decide what your app is great at

First we must determine the scope of our app and define the experience goals that will guide us
through the rest of the design process.

What’s your app about?

To get started let’s make a list of the functionality we want our app to provide to users:

 Get a list of Work list items from Dynamics AX 2012

 Get notifications when new Work list items are created
 Let the user read the notification messages
 Let the user take action on items with a workflow

What’s your app great at?

Now that we have an idea of what our app will do, we need to determine our app’s “great at”
statement.

Examples:

 My Work list app is great at helping Dynamics AX users stay connected to their business
 My Work list app is great at helping Dynamics AX users quickly take action on items
requiring their attention
 My Work list app is great at providing decision makers with timely information

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 3 OF 26

 2.2. Step 2 – Decide what user activities to support

With our “great at” statement determined we must now create user flows. The flow represents a
set of related interactions that users have with the app to achieve their goals. The flows should be
easy to learn and require the fewest interactions possible.

What should users be able to do?

First we must create a list of the flows for our app. Our Work list app is “great at helping Dynamics
AX users take action on items requiring their attention.” So some of the flows we will want to
highlight are:

 View current Work list items

 Receive notification when a new Work list item is available to be read
 View a Work list item message
 Delete a Work list item
 Perform an Accept action on a Work list item
 Perform a Deny action on a Work list item
 Perform a Reject action on a Work list item

2.3. Step 3 - Decide what features to include

Once we have determined what our app will do, we need to take a look at features available in the
Windows 8 platform that we want to include. We also need to ensure that each feature
implemented aligns with the Windows 8 user experience (UX) guidelines.

App Contracts

Our Dynamics AX app can participate in app contracts that enable broad, cross-app, cross-feature
user flows.

Features we will want to include with our Work list App are:

 Search – Let users search through Work list items from anywhere in the system, including
from within other apps.
 Share – Let users share Work list item information via email
 Background tasks (Extension) – Let the app retrieve notifications from Dynamics AX even
when the app is suspended
 Settings – Provide quick in-context access to settings. For example the connection
information required to synchronize with Dynamics AX.

Detailed information on App contracts and extensions available may be found here

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 4 OF 26

 Different views and form factors

Windows 8 apps by be used on many different form factors with different inputs. In planning the
design of the app it will be important to ensure that the user experience is good on both touch and
non-touch devices.

3. Development - Building a simple window 8 app that integrates with Dynamics AX

2012 R2

Once you have completed the planning phase, it will be time to get started with development. In
this guide we will walk through building a simple App to help you get started with building your
own Windows 8 apps that integrate with Dynamics AX 2012.

3.1 Step 1- Prepare an AIF service in Dynamics AX 2012

In order to access data in your Windows 8 App, an AIF service will need to be available to
reference. In this example we will build a Windows 8 app that allows a user to view their worklist.

First, we need to create a service that exposes the worklist. To begin we need a query which can
be used to base the service. Luckily a query already exists in the AOT that will meet our needs. The
query is: EventAlertForUser

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 5 OF 26

 Now that we have a query we can use the AIF Document Service Wizard to create the required
service classes.

1. Go to Tools -> Wizards ->AIF Document Service Wizard

2. Step through the wizard and select the query: EventAlertForUser

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 6 OF 26

 3. Choose the service operations that are required, in this example we will only enable read and
find.

4. Once your selections have been made, generate the service classes.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 7 OF 26

 5. Under your private projects in the AX developer workspace a new project should now exist
named: AxdEventAlertForUser

6. In the Dynamics AX 2012 client navigate to System administration->Setup->Services and

Application Integration Framework->Inbound ports

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 8 OF 26

 7. Create a New port and name it WorkListService. For the Adapter type choose either NetTcp or
HTTP. In this example HTTP will be utilized.

8. Under the Service contract customizations tab select Service operations.

Select the following service operations:

 EventAlertForUserService.find
 EventAlertForUserService.read

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 9 OF 26

 9. Under the Service contract customizations tab select Data policies.

Enable the following fields:

 Message
 NotificationSource
 NotificationType
 Subject
 TypeId
 UserId
 Visible

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 10 OF 26

 The schema output should match the following:

10. Under the troubleshooting tab set the logging mode to: All document versions. This will help in
case you need to investigate any issues with the service.

11. Once the service is configured activate it using the Activate button. (This may take a few
minutes depending on the speed of your environment).

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 11 OF 26

 12. Once complete an Infolog will pop up, scroll down and ensure that the WorkListService was
started.

13. If you are developing with the Dynamics AX 2012 R2 Demo VM 1.5 image, the address
generated for the web service is:
http://ax2012r2a:89/MicrosoftDynamicsAXAif60/WorkListService/xppservice.svc

By following the link the following webpage should display in your web browser:

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 12 OF 26

 14. If you were able to see the page the new web service has been created and we’re ready to
proceed to the next step which takes us into Visual Studio 2012.

3.2 Step 2- Create a new Windows Store App Project in Visual Studio 2012

Open up Microsoft Visual Studio 2012 and select the Split App (XAML) template under Visual C# ->
Windows Store.

Upon the initial creation of the project the solution structure should have the following items:

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 13 OF 26

The areas that we will focus on are:

 References – this is where we will create a reference to the Dynamics AX web service that
was created earlier.
 Assets – Any images we want to use in our app will be stored here.
 DataModel – In the example we will leverage the sample data model.
 App.xaml – App resources such as the AppName can be found here.
 ItemsPage.xaml – we’ll update the look of this page in Blend.
 Package.appxmanifest – This holds the properties of the apps deployment package.

3.3 Step 3- Configure the Package.appxmanifest

Let’s get started by making a couple changes to the appxmanifest. Right click on the appxmanifest
and open it up.

From the Application UI page we can set the name for are App, supported rotations, and logos.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 14 OF 26

 If you chose to use a NetTCP service and plan to use Windows Authentication with your Windows 8
App and Dynamics AX some configuration will be required in the Capabilities tab.

Enable the following if your app will use NetTCP:

 Enterprise Authentication
 Private Networks (Client & Server)

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 15 OF 26

 3.4 Step 4- Create a Service Reference to a Dynamics AX AIF Service

Let’s get started with wiring up our new Windows 8 App to Dynamics AX. First we will need to
create a service reference. Since Dynamics AX creates services based on WCF this is very
straight forward within Visual Studio.

1. Right click on References from the Solution Explorer and select Add Service Reference.

2. Enter the following address into the form and hit the Go button:
http://ax2012r2a.contoso.com:89/MicrosoftDynamicsAXAif60/WorkListService/xppservice.s
vc

The two operations that were enabled earlier within Dynamics AX should be visible.
Name the service WorkListService and hit OK.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 16 OF 26

 Once the service has been referenced it should show up in the Solution Explorer under the
Service References folder.

3.5 Step 5- Consume data from Dynamics AX within a Windows 8 App

Now that are app is connected to the Dynamics AX AIF web service, we’re ready to start consuming
data.

1. First I am going to create a new class to work in called DynamicsAXConnector.

To use the service we need to create an instance of the client object.

We’ll also need an instance of FindResponse object for the data we’ll get back from the service.

2. For our method we need to use an asynchronous call. Windows 8 Apps are take full advantage
of threading and asynchronous programming.

You notice that this method was created as an async Task and it returns a List. The service call
must be performed asynchronously so the method must be defined as async. If you are new to
asynchronous programming I recommend reading the following article on MSDN: Asynchronous
Programming with Async and Await (C# and Visual Basic).

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 17 OF 26

 3. Creating the query criteria object is the next step. We must create a QueryCriteria object and a
CriteriaElement object.

4. With the query objects created, we can now set the criteria values.

It is important to set the DataSourceName correctly. This must be provided for the query to
function.

5. Once the criteria has been set the find operation may be executed.

Note that the find method was called with await.

6. Once data can come back from the service we will iterate through it and put it in a generic list
collection.

For the purposes of this example only the Alert worklist messages will be utilized.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 18 OF 26

 3.6 Step 6- Present data from Dynamics AX within a Windows 8 App

We now have data from Dynamics AX 2012 in our Windows 8 app. For this example I am going
to re-use the SampleDataSource that was created with our template project.

1. The data has to be synced on an async event. For this example, the call to AX AIF web
service has been added to LayoutAwarePage.cs. The method is OnNavigatedTo , this is
invoked when a page is about to be displayed in a frame.

Before the OnNavigatedTo method can be used to call the service we must turn it into an
async method.

2. The following code is added to the OnNaviagedTo method to refresh the data.

To temporarily store data a new class was created named AXDataSource. This simple class
has a static List which is used to store the workListItems.

3. Once we have data populated in workListItems it can be used by the SampleDataSource

which is called by the LoadState method of the page. This is called at the end of the
OnNavigatedTo event.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 19 OF 26

 Each page has a LoadState event where logic can be placed that must execute before the
page is displayed. For example the ItemsPage.xaml.cs class LoadState method contains
logic for populating the view model with sample data.

By default the SampleDataSource creates hard coded sample data in the classes
constructor: SampleDataSource(). For the example we will populate the first item group
with Alert worklist messages from Dynamics AX.

The SampleDataSource may be useful for creating proof of concept Windows 8 Apps. The
other groups may be easily manipulated since they are built from hard coded data.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 20 OF 26

 4. Now that data has wired to the SampleData source we can run our Windows 8 App. Visual
Studio debug apps on your local machine, a simulator, or a remote machine.

The first item group should now display Alerts and the number of messages that were
retrieved from Dynamics AX. Note that since the call to query the web service is using
await, the items will not display until data has been retrieved.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 21 OF 26

 If you click on the Alerts, the item split view page will display.

At this point message data from Dynamics AX 2012 for alert worklist items will appear.
Many of the alert messages lack a message body; the App is only as good as the data.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 22 OF 26

 4. Using Blend to enhance the UX of your Windows 8 App

Next we will take a quick look at some ways to quickly change the look and feel of your
Windows 8 app with Blend.

1. Open the example solution in Blend by right clicking on the solution from Solution Explorer
and selecting Open in Blend.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 23 OF 26

 2. Once you are in Blend the UX design may be modified either through the design view or
directly in the XAML code.

3. For my example Windows 8 app, I wish to apply a standard background to all of my Apps
pages. To do this I need to modify my resource dictionary which is defined in the App.xaml
file.

The resource dictionary is currently set to use the StandardStytles.xaml file.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 24 OF 26

 4. At the bottom of the StandardStytles.xaml file the style LayoutRootStyle is defined.

Set the background property to an image you wish to have displayed. By default any
images used by your app should be saved to the projects Assets folder.

5. Next let’s take a look at how to modify the default template used to create new items in
the grid view. Right click on the ItemsPage.xaml ItemGridView control from design view in
Blend. Select Edit Additional Templates -> Edit Generated items (ItemTemplates)->Edit
Current

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 25 OF 26

 6. The DataTemplate should now be displayed. Here you can modify the look and feel of the
items that will be generated in the grid view.

5. Conclusion

In this guide we have walked though creating a simple Windows 8 App that integrates with
Dynamics AX 2012 R2. Due to the use of the Windows Communication Foundation (WCF),
accessing data from Dynamics AX 2012 is simple to do.

Windows 8 provides a wonderful new opportunity to build engaging solutions that work great
on many different device form factors. This allows users to interact with their data from
applications such as Dynamics AX in many new and exciting ways.

Have fun building your Windows 8 Apps and be sure to check for the latest version of the
Dynamics AX Windows 8 App Starter Kit on CodePlex.

APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 26 OF 26