Microsoft Dynamics Mobile Team blog : development

How to enable barcode scanning on existing Microsoft Dynamics Mobile tasklets

Jan Zeman — Tue, 07 Apr 2009 00:07:40 GMT

This is an installment of Barcode Scanning With Microsoft Dynamics Mobile series.

… and concurrently it is the shortest blog article I have ever written :-)

Just follow the MSDN link: How to: Set Up Barcode Scanning for Mobile Sales. Use this approach for SimpleList or similarly for ItemList tasklet.

Where To Get Barcode Drivers

Jan Zeman — Wed, 21 Jan 2009 21:46:00 GMT

This is an installment of Barcode Scanning With Microsoft Dynamics Mobile series.

Barcode drivers are the most essential prerequisites for barcode scanning functionality on a particular device. Out of the box, Microsoft Dynamics Mobile supports two barcode enabled device manufacturers: Motorola (formerly Symbol) and Intermec. To achieve any barcode related functionality you need to acquire appropriate barcode drivers. These are usually wrapped in some .NET Compact Framework assembly which is shipped as a part of a particular SDK of the given manufacturer. Third parties (in this case Microsoft) are not allowed to redistribute manufacturers’ drivers so you have to get them by your own. To make your life easier I prepared the following mini-tutorials describing where to download appropriate SDK and how to extract barcode driver out of them.

Please notice! The description below is very precise and all links are currently working (January 2009). However it can change as time goes by. Feel free to add your comment to the blog article, we will update the description.

Motorola (formerly Symbol): You need two assemblies called Symbol and Symbol.Barcode

Go to Motorola EMDK for .NET v2.0 (EMDK stands for Enterprise Mobility Developer Kit formerly known as SMDK - Symbol Mobility Developer Kit) and download EMDK-M-020005-Up2.zip.
Unzip and locate the following CAB file: symbol.all.arm.cab (typically in .\SDK\Smart Devices\wce500\armv4i folder).
Install the CAB file on any Windows Mobile device or emulator, and locate Symbol.dll and Symbol.Barcode.dll on that device under \Windows
Copy Symbol.dll and Symbol.Barcode.dll to your PC for future use.

Intermec: You need one assembly called Intermec.DataCollection.CF2 a

Notice that you must be a registered user to be able to perform any download from the Intermec web site. If you are not, go to the Intermec downloads login page, click on the “create a new account” link, provide all required information and click on the “Register” button.
Having your Intermec account you can download the Intermec Development Toolkit. You must enter your Intermec account credentials and go through a short wizard to reach the download link.
Install the toolkit (00002344_IDLDCRK_Setup.exe).
Locate Intermec.DataCollection.CF2.dll assembly under the following path: %PROGRAMFILES%\Intermec\Developer Library\Dot NET Assemblies\CF 2.0
Copy Intermec.DataCollection.CF2.dll to your PC for future use.

Barcode Scanning With Microsoft Dynamics Mobile

Jan Zeman — Wed, 21 Jan 2009 21:40:00 GMT

My plan is to post a short series of articles related to barcode scanning experience with Microsoft Dynamics Mobile. Today’s post should act as an overview of posted and will-be-posted articles touching the barcode functionality.

Here is the plan:

Barcode scanning prerequisites: Where to get barcode drivers
How to enable barcode scanning on existing Microsoft Dynamics Mobile tasklets
How to code your own barcode enabled tasklets (Motorola and Intermec devices)

Bullets above will be transformed to http links after the corresponding article has been issued.

Unit Testing DocumentHandlers With Parameters

ploeh — Tue, 13 Jan 2009 09:20:38 GMT

In my previous post, I described how to unit test custom DocumentHandlers. When your DocumentHandler has one or more DocumentHandlerParameters, you have to manually assign values to these, since, during unit testing, the DocumentHandler instance runs outside the warm and fuzzy Mobile Server environment.

This is as simple as setting the property to the desired value before invoking the Submit or GetDocumentDescription methods.

[TestMethod]

public void TestUsingMyIntegerParameter()

    // Fixture setup

    string anonymousNumber = 7.ToString();

    MyDocumentHandler sut = new MyDocumentHandler();

    sut.MyInteger = anonymousNumber;

    // Exercise system

    // ...

    // Verify outcome

    // ...

    // Teardown

Notice how, in the above test, the MyInteger property is assigned to an Anonymous Variable before the SUT is exercised.

It's very simple, so the main purpose of this post was just to remind you that you have to remember setting all relevant properties appropriately as part of setting up your Fixture.

Unit Testing DocumentHandlers

ploeh — Wed, 07 Jan 2009 12:06:00 GMT

As I promised in a previous post, I'd like to discuss how to unit test a custom DocumentHandler. There's really nothing to it: Just create a new instance of your DocumentHandler and start invoking its members.

Here's a test of the Submit method:

[TestMethod]

public void SubmitWillReturnCorrectDescription()

    // Fixture setup

    string anonymousXml = "<anonymous>XML</anonymous>";

    Guid anonymousMessageId = Guid.NewGuid();

    string anonymousDeviceId = "Anonymous device ID";

    IPrincipal anonymousPrincipal =

        new GenericPrincipal(

            new GenericIdentity("Someone"), new string[0]);

    string expectedDescription =

        string.Format("Message {0} was successfully submitted",

        anonymousMessageId);

    MyDocumentHandler sut = new MyDocumentHandler();

    // Exercise system

    DocumentResponse result =

        sut.Submit(anonymousXml, anonymousMessageId,

        anonymousDeviceId, anonymousPrincipal);

    // Verify outcome

    Assert.AreEqual<string>(expectedDescription,

        result.Description, "Description");

    // Teardown

Since the Submit method takes four parameters, you must create these four objects prior to invoking the method. In this example, I'm naming the variables using the Anonymous Variable Naming coding idiom.

In many cases, the XML string containing the document to submit is probably the most interesting parameter, and you will likely need to write many separate tests to verify that your custom DocumentHandler correctly deals with different instances of your particular XML document format.

In this context, it's worth noting that you can obviously debug into your code when running a test, so this is a very effective troubleshooting technique. Due to the way we load and host DocumentHandlers, it's not possible to attach a debugger to a custom DocumentHandler while it's executing in Mobile Server, so debugging into a unit test is a good alternative. If your custom DocumentHandler throws an exception while executing in Mobile Server, the event log will contain a copy of the message, and you can then use this copy to reproduce the problem in a unit test.

In the test shown above, notice that I create a new GenericPrincipal instance to use as the mobileUser parameter. Be aware that any IPrincipal instance is acceptable, so I just created a GenericPrincipal because it was the easiest thing to do. When executing your custom DocumentHandler, Mobile Server doesn't use GenericPrincipal, but rather a different implementation of IPrincipal, and it makes no guarantees that it will always use the same implementation type. In other words, your custom DocumentHandler should follow the Liskov Substitution Principle.

As you can see, it's really straightforward to unit test custom DocumentHandlers. The Submit method has by far the most complex signature, so testing the FriendlyName and GetDocumentDescription members is even simpler.

Update: A follow-up post dealing with unit testing and DocumentHandlerParameters is now available.

DocumentHandlerParameter Best Practices

ploeh — Thu, 18 Dec 2008 16:47:12 GMT

When you create a custom DocumentHandler, it is very likely that you may need to supply it with some configuration data. Common examples include the address of your back-end server, credentials to the back-end system, etc.

DocumentHandlers can be configured by adding public read/write string properties and decorating them with the DocumentHandlerParameter attribute. This is all described in the documentation, but in this post, I'd like to expand a bit on the subject to describe some best practices for dealing with such parameters.

If all you need is a string, you can get by with an implementation as simple as this:

[DocumentHandlerParameter("Description template")]

public string DescriptionTemplate { get; set; }

However, if you really need something else, you will have to parse the text yourself, since only strings are supported. Imagine that you really need to expose an integer property. Basically, you have two options:

You can parse it as the value is being assigned
You can parse it when you need it

Parsing the value right away is the preferable alternative, since this gives Mobile Server a chance to verify the configuration as soon as the operator saves the document type (right now, Mobile Server doesn't do that, but it might do that in a future version, in which case you'll get validation for free). It also makes for cleaner code.

Here's one possible implementation of an integer property:

[DocumentHandlerParameter("My integer")]

public string MyInteger

    get { return this.myInt.ToString(); }

set

        int i;

        if (int.TryParse(value, out i))

            this.myInt = i;

            return;

        throw new ArgumentException(

            "Value was not an integer", "value");

where myInt is a private member variable. Notice how the setter attempts to parse the string to an integer, and throws a descriptive exception if this is not possible.

Whenever the value of this property is required, the rest of the code can simply reference this.myInt, which is now guaranteed to be correct. Int32 is a value type, so referencing this.myInt will always be correct, since the default is 0.

This is not the case for reference type properties like the DescriptionTemplate property above. Keep in mind that reference types may be null, so that it becomes necessary to check for this before using the property:

public override DocumentResponse Submit(string xmlDocument,

    Guid messageId, string deviceId, IPrincipal mobileUser)

    string template =

        string.IsNullOrEmpty(this.DescriptionTemplate) ?

        "Message {0} was successfully submitted" :

        this.DescriptionTemplate;

    DocumentResponse dr = new DocumentResponse();

    dr.Description = string.Format(template, messageId);

    return dr;

In this implementation of the Submit method, I test the DescriptionTemplate property's value before using it, defaulting to a hard-coded value if it's not defined. It is important to realize that Mobile Server makes no guarantee regarding the values of DocumentHandlerProperties, since it is entirely up to the operator whether he or she cares to fill in the values or not, so either have some good default values or throw an exception with a descriptive error message.

As the above example illustrates, you can reference DocumentHandlerProperties from within the Submit method. This is the main scenario, but Mobile Server will also fill in the values of these properties when invoking the GetDocumentDescription method.

As a contrast to the Submit and GetDocumentDescription methods, the FriendlyName property of DocumentHandler is only being used in the UI when the operator selects a DocumentHandler to configure; that is, before the properties are being configured. For that reason, when the code inside the FriendlyName property executes, the property values will always have their default values.

In short:

Validate parameter values in their setters and fail fast.
Don't assume values have been set.
Consume values from Submit and GetDocumentDescription only. You cannot consume the values from within the FriendlyName property's code.

DocumentHandler - Behind The Scenes

ploeh — Thu, 11 Dec 2008 17:18:00 GMT

Mobile Server gives you the option of developing custom code that integrates to your back-end system. One way you can do this is by implementing one or more .NET classes that derive from the abstract DocumentHandler class. This is already described in the documentation along with the other options for back-end integration, but in this post, I'd like to provide some background information on this API. In future posts, I'll discuss some best practices for developing custom DocumentHandlers.

Here's the DocumentHandler API to establish the context:

public abstract class DocumentHandler

    protected DocumentHandler();

    public abstract string FriendlyName { get; }

    public abstract string GetDocumentDescription(

        string xmlDocument);

    public abstract DocumentResponse Submit(

        string xmlDocument, Guid messageId,

        string deviceId, IPrincipal mobileUser);

When we designed DocumentHandler, we had several design goals in mind:

It should be as simple as possible to implement a custom DocumentHandler
It should provide as much flexibility as possible
It should be testable
It should adhere to the .NET Framework Design Guideline that states that you should prefer abstract classes over interfaces (consequently, this is why DocumentHandler is not an interface)
It should be CLS compliant

While I personally could wish for even more flexibility, I think we succeeded very well on all the other points. In the Dynamics Mobile Team, we use TDD, so it was particularly important to us that the DocumentHandler API is testable - and it is.

The DocumentHandler constructor is empty, so we don't require you to pass some weird, internal or sealed object as a constructor parameter; on the contrary, in fact we require that your custom DocumentHandler has a default constructor. That makes it super-easy to create a new instance as part of a test:

MyDocumentHandler sut = new MyDocumentHandler();

All the members of DocumentHandler works on well-known BCL types (string, Guid, and IPrincipal) with the single exception of the Submit method, which returns a DocumentResponse instance, which is a type that we have defined in the same library.

DocumentResponse is a public, non-sealed class with a default constructor, and it works almost exclusively with BCL types such as string, DateTime, bool, etc. Again, there's a single exception in the use of the DocumentResponseStatus enum, but also here we are dealing with a public type that is easily created.

The bottom line is that the entire DocumentHandler API contains only three custom types, and all of those types are very susceptible to unit testing.

In a future post, I will discuss the matter of unit testing custom DocumentHandlers in greater detail.

Additional place to get help using Microsoft Dynamics Mobile bits

Tim Skauge — Mon, 23 Jun 2008 14:40:00 GMT

As a non official role in our team I’m searching the internet for people who needs help using our bits, and has on several occasions helped. I would like to point you to a site where you can get some quality answers without waiting for the team to write...(read more)

Using SSIS with Microsoft Dynamics Mobile

Jan Zeman — Sat, 14 Jun 2008 12:54:00 GMT

Let me start with a small announcement I am happy to announce that we have upgraded our SSIS ( SQL Server Integration Services ) solution for Mobile Sales from the 2005 to the 2008 version of Microsoft SQL Server Integration Services. So from now on we...(read more)

How to send a requestdocument from a service

Tim Skauge — Tue, 27 May 2008 10:00:00 GMT

Yesterday I was sitting with a potential partner here at MDCC (Microsoft Development Center Copenhagen) to get them introduced to Microsoft Dynamics Mobile. All in all I think we had a good and productive day where we covered most of the major topics...(read more)