Alright, so making use of Service References in Dynamics AX 2009 has been out for a little while. In the past I have done post talking about white papers, and how-to's. Talking about the design of such services.
Well I wanted to take a little time and spend a little bit with creating custom WCF services, and then consuming those services within Dynamics AX.
This is not the first such tutorial on the web. There was some earlier one's done when Dynamics AX 2009 first came out. What I want to address however is details for creating a simple service, in general terms. Talk about the different aspects of these general concepts. Then in later post move through wht WCF services, over other options, and also common issues found when scaling services, promoting to other instances like production, etc.
So first lets look at a custom WCF Service. The following is such a service.
1.) A DataContract.:
2.) A ServiceContract, Defined in an Interface
3.) The underlying class that implements the given ServiceContract Interface and it's underlying OperationContract's
And
So the above show's a TestBed namespace, that includes a Class with an interface. That interface is what defines the ServiceContract and underlying OperationContracts. These are used to define what endpoints exists for consumption by a WCF client.
The DataContract, FooData, is used to define a complex (though simple example) user defined type, with properties that exist to describe what a FooData object is.
Once these are defined, I recommend actually first testing by consuming in .Net. Maybe through a Console app or .Net Windows Form. This will help to get rid of any security issues that might exists for IIS, etc.
Once this is tested, now we can move forward with consuming this within Dynamics AX.
Simply create a new project, add a new group for references, right click, add new Service reference, point to the URL where the FooSvc.svc is being hosted, and AX will create a client, used by the AOS to interact and consume this WCF custom service.
Once that is done, then you can do something similar to the following X++ code, that calls, interact, and works with the WCF Service, Operations and DataContract.:
Now lets disect some of this, and look into the details. So before this WCF Service could be consumed, it had to be created, and then published to a place where AX could consume it.
Since the idea it to talk in general terms, the Foo code concept was used, in order to be general.
So this Foo based C# .Net 3.5 code example shows a simple example of a Foo Class, that has an interface. It's important to understand that this is very similar to typical interfaces for classes. It governs how outside clients, consumers and code can interact with the class and create instances of it.
What different about this interface is the meta tag information, used by the WCF hosting .Net code to define what the given interface, and methods are. That is a ServiceContract, and OperationContract's. Or what's also know as endpoints.
These endpoints, are what AX consumes and works with. As you can see in the X++ code, .GetFooDataList(5); and .GetFooString(fooData);.
The actual code that does operate on the calls, and parameters variables sent in, lives in the public class Foo : IFoo {...}. The IFoo is familiar to anyone that has worked with C# code before.
Now to generate this interface, and class approach, simply add a new WCF Service and the wizard creates a shell for you.
Lets move forward, a look at the DataContract. Now this is different than what we have seen before in working with straight .Net Code, and .Net code through Dynamics AX, X++.
This is used to define a complex custom type, that can be passed between the WCF service code, and a consuming client. This includes Dynamics AX.
Now note, that the DataContract, FooData, is made up of simple data types, for it's DataMembers. However with this defined, and once a service reference is made from within AX, then the give FooData DataContract class, can now be passed back and forth between Dynamics AX X++ and C#.
You can see in the X++ example, that once I get the FooData based List, that I can call a method from WCF C# service, and send it a .Net object defined in that service as FooData. This can be filled with information, passed in and then operated on within the WCF service. The return, note is a simple return.
Let's also take a step back here, and look at how I get my FooData object. I am working with what appears to be an Array of FooData[]. And what I am working with is actually a List. You can see the return type for .GetDataList(5); method call.
Notice how I create an instace of the System.Collections.IEnumerator, and use that to Enumerate through the List of FooData objects.
I think it's very important to understand that you can work with List's, and specific Genrics based list that define a List with specific types that are contained within.
It's actually a pain point, if your not familiar with working with Arrays and List with WCF in general, and much less with WCF Services consumed with Dynamics AX. So this is a very good example of proven code that works for working with List of not just simple strings, etc. but actual custom complex types.
So what we have here is some basic concepts of a simple WCF C# service, that has a few OperationContracts, for our Foo.svc ServiceContract. It also has a custom DataContract used in both the X++ and C# code. And this complex type can be sent between the two.
Now one could take this simple example, and really make use of it for creating needing code in a WCF service layer. Maybe for working with other LOB, line of business, applications. Maybe for working with legacy code, or objects, or an enterprise sevice bus, with middleware message needs.
What I do want to point out, is there are certain Dynamics AX Service Reference settings, gotchas, watch outs, etc. Espically when you move from Dev to Production. Or if you need to change the WCF service and regenerate the reference inside Dynamics AX.
I plan on going over those details a little later, and taking this post further into real world solutions.
I hope this gets you thinking though about WCF services, and the power of WCF Services. As i mentioned at the start of this post, I plan on covering WCF Services vs. Web Services and why choose WCF services. Also in that next post I will cover the gotchas and watch outs I mentioned above.
See you next time!
P.S. In the meantime if you have specific questions, issues, something you would like to see with this, please leave me a comment or shoot me an email.
"Visit the Dynamics AX Community Page today!"
Labels: .Net, C#, Code Example, Dynamics AX 2009, Service Reference, WCF, WCF Service, X++, Xpp
