Microsoft Dynamics AX Windows 8 App Starter Kit. App Development Guide Version 1.0

Transcription

1 Microsoft Dynamics AX Windows 8 App Starter Kit App Development Guide Version 1.0

2 Table of Contents Microsoft Dynamics AX Windows 8 App Starter Kit... 1 App Development Guide Version Introduction Building your first Dynamics AX App for Windows Step 1 Decide what your app is great at Step 2 Decide what user activities to support Step 3 - Decide what features to include Development - Building a simple window 8 app that integrates with Dynamics AX 2012 R Step 1- Prepare an AIF service in Dynamics AX Step 2- Create a new Windows Store App Project in Visual Studio Step 3- Configure the Package.appxmanifest Step 4- Create a Service Reference to a Dynamics AX AIF Service Step 5- Consume data from Dynamics AX within a Windows 8 App Step 6- Present data from Dynamics AX within a Windows 8 App Using Blend to enhance the UX of your Windows 8 App Conclusion APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 2 OF 26

3 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 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

4 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 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

5 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 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

6 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

7 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

8 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

9 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

10 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

11 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 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: By following the link the following webpage should display in your web browser: APP DEVELOPMENT GUIDE VERSION 1.0 PAGE 12 OF 26

13 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 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

14 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

15 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

16 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: 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

17 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

18 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

19 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

20 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

21 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

22 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

23 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

24 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

25 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

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