Creating several Microsoft Tags at once

Microsoft tags are a type of barcode you can scan with your mobile phone. They connect physical objects and printed material to text, images and media on the web. You may have seen them printed in magazine ads, billboards, or product packaging. Anyone can create and print tags. Microsoft’s tag manager lets you sign up and create tags for free. You can point your tags at your website pages, and import their images to any graphic software that you use to create printed material.

Some sample tags

Some sample tags

The Tag manager website is great for creating a handful of tags. If you have to create more of them, however, Tag manager can become tiring, and fast. To that end, Microsoft provides the Tag API. The Tag API lets developers create and update several tags at once. The Tag API is available as a SOAP web service that can be invoked from numerous software environments. In this article, we will put together a small .NET Framework applet that lets you create a any number of tags.

Getting started with the Tag API

Visit http://tag.microsoft.com/developer/index.aspx to get acquainted with the Tag API. To get started, you will need to set up your free Tag Manager account, and then obtain an API key. If you haven’t already, go to the tag manager website and click the TAG MANAGER link at the top right to get started. The signup process is straightforward. Once inside the Tag manager, you can see your (empty) list of tags. At this point, you should be able to request an API key. The API key looks like a string of 30 or so hex digits, not unlike a GUID.

Your first TagAPI program

With the API key in hand, we can get started. Fire up Visual Studio, and create a new console application. In the Solution Explorer view, right click References and select Add Service Reference… In the Add Service Reference dialog window that pops up, type in the address of the Tag API: https://ws.tag.microsoft.com/MIBPService.wsdl and click Go. The MIBPService will show up in the Services list. If you expand it and select the IMIBPContract underneath, the list of supported operations will show. Modify the namespace  to “Tag” and click OK to proceed. A service reference to the Tag API will be added to your project.

Adding a service reference

Adding a service reference

Adding the Tag API service reference

Adding the Tag API service reference

To use the Tag API in your program, first add a using statement with its namespace. I named my application “MakeTags” — use your application’s namespace as the prefix there. The second part of the namespace, “Tag”, is the value entered in the Namespace box of the Add Service Reference window.

using namespace MakeTags.Tag;

To invoke Tag API services, we will need to create two objects. One represents the Tag API service, and the other represents our API key. Make sure to insert the API key you applied for into creds.AccessToken. In your program’s Main function, add:

static void Main(string[] args)
{
    MIBPContractClient tagService = new MIBPContractClient();
    UserCredential creds = new UserCredential();
    creds.AccessToken = "your-access-token-here";
}

To create a single Tag, we could add the following code to invoke the CreateTag method. Make sure to use a new tag title. Trying to create a tag with a title of a tag you created before will fail. Also note that the tag category has to exist before you call CreateTag. I used the “Main” category, that is supposed to be created for you on your new Tag account. But it has been a long time since I created my account, and I may be wrong. If needed, you can create a category from Tag Manager, or invoke the CreateCategory method to create a new one.

string tagTitle = "Tag title here";
string category = "Main";

URITag tag = new URITag();
tag.Title = tagTitle;
tag.MedFiUrl = "https://flyingpies.wordpress.com/2011/05/24/creating-several-microsoft-tags";
tag.UTCStartDate = DateTime.UtcNow;
tagService.CreateTag(creds, category, tag);

At this point, if all is well, the program can run and create a new tag. Try it out, and look for your new tag inside Tag Manager. Running the unmodified program again will fail — because we already have a tag with this name. Modify the tag name before you run the program one more time. Here’s the complete program:

using System;
using MakeTags.Tag;

namespace MakeTags {
    class Program {
        static void Main(string[] args) {
            MIBPContractClient tagService = new MIBPContractClient();
            UserCredential creds = new UserCredential();
            creds.AccessToken = "your-access-token-here";

            string tagTitle = "Tag title here";
            string category = "Main";

            URITag tag = new URITag();
            tag.Title = tagTitle;
            tag.MedFiUrl = "https://flyingpies.wordpress.com/2011/05/24/creating-several-microsoft-tags";
            tag.UTCStartDate = DateTime.UtcNow;
            tagService.CreateTag(creds, category, tag);
        }
    }
}

Rendering the tags

To print the tags, we will need to render them as images. The GetBardcode method asks the Tag API service to render the tag for us in one of several image formats. In addition to several bitmap formats (png, jpeg, gif, tiff), GetBarcode can also return a PDF rendering of the tag. You can also specify whether you want the rendered tag to include instructions for the user to download the tag mobile phone app.

Adding the following at the bottom of the program almost does what you would expect:

string tagImageFilePath = "mytag.png";
byte[] tagImageBytes = tagService.GetBarcode(
    creds,
    category,
    tagTitle,
    ImageTypes.png,
    1f,
    DecorationType.HCCBRP_DECORATION_DOWNLOAD,
    false);
System.IO.File.WriteAllBytes(tagImageFilePath, tagImageBytes);

If you run the program at this state (make sure to use a new title, or delete the old tags), it will fail in GetBarcode. The exception complains: “…The maximum array length quota (16384) has been exceeded while reading XML data. This quota may be increased by changing the MaxArrayLength property on the…”. The service reference that we added in the beginning limited itself to 16K of data, but our tag image apparently needs a few more bytes (at our chosen image format and size, about 45K are needed.) This is easy to fix. In the application’s app.config file, find the line that contains maxArrayLength=”16384″ and replace it with a higher value. I used maxArrayLength=”100000″:

<readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="100000"
    maxBytesPerRead="4096" maxNameTableCharCount="16384" />

Now our program runs to completion, and leaves an image file of the rendered tag in its startup folder. Here’s the image created from the snippet above. Go ahead, scan it with the tag reader on your mobile phone!

A sample rendered tag

A sample rendered tag

Several at once

Now that we know how to create and render tags, we can do so in a loop. Here’s the complete program:

using System;
using System.IO;
using MakeTags.Tag;

namespace MakeTags {
    class Program {
        static void Main(string[] args) {
            MIBPContractClient tagService = new MIBPContractClient();
            UserCredential creds = new UserCredential();
            creds.AccessToken = "your-access-token-here";

            int tagsToCreate = 10;
            string category = "Main";
            string tagTitlePrefix = "My Sample Tag ";
            string tagImageFilePathFormat = "mytag{0}.png";

            for (int i = 0; i < tagsToCreate; ++i) {
                Console.WriteLine("Creating tag " + i);

                string tagTitle = tagTitlePrefix + i;

                URITag tag = new URITag();
                tag.Title = tagTitle;
                tag.MedFiUrl = "https://flyingpies.wordpress.com/2011/05/24/creating-several-microsoft-tags";
                tag.UTCStartDate = DateTime.UtcNow;
                tagService.CreateTag(creds, category, tag);

                string tagImageFilePath = string.Format(tagImageFilePathFormat, i);
                byte[] tagImageBytes = tagService.GetBarcode(
                    creds,
                    category,
                    tagTitle,
                    ImageTypes.png,
                    1f,
                    DecorationType.HCCBRP_DECORATION_DOWNLOAD,
                    false);
                File.WriteAllBytes(tagImageFilePath, tagImageBytes);
            }
        }
    }
}
The rendered tags

The rendered tags

Advertisements