09 August 2015

Windows 10 maps part 1 - setting up

Ever after my TechDays 2015 talk I have been getting a lot of questions about the new Universal Windows App map control for  Windows 10, and now the launch is done and the "getting things done" mind set (the very point of Windows anyway) is setting in, I have decided to make some time to write down how to get things done indeed - with the said map control.

To prevent this becoming an insanely huge post that will take forever to complete (and read) this is going to be a seven part series.

  1. Setting up
  2. Manipulation and drawing
  3. Querying the map & attaching business objects to map shapes
  4. Theme & Options
  5. Styles & 3D
  6. Scenes & camera
  7. Using external maps with TMS/WMS

During the blog series I will refer to a sample app that I have published on GitHub already.

By the way: this may not become a continuous series: it's very well possible some stuff gets published in between, as I am currently very much exploring the Windows 10 CoreIot stuff and plan to write about that as well.

Getting a key
During the course of the various versions of Windows and Windows Phone development we needed some key of a kind. Where we needed to get that varied over time and platform, but we now have one Windows thus one place to get the key: the Bing Maps dev portal. You login to that portal using your Microsoft account, Truth to be told, it's not the most beautiful nor the most intuitive of sites I have ever seen, and the only service announcement dating back to February 2015 makes it feel a bit like an abandoned site, but it is the real McCoy and it does the trick.

You click "My account"  and then "Create or view keys"

This will take you to this screen where you can see your existing keys, and create new ones. Curiously it's not possible to delete keys.

When you click "here" in "click here to create a new key" this will give you the following popup

You can leave the Application URL box empty. Important is that you select "Universal Windows App". Fill in the name, and leave the Key type to "Basic" - at the time of writing this it was the only choice anyway. The result will be a rather long affair - the keys I have created are 220 characters long.

Use your key in code or XAML
There are actually two ways of putting your key to work: you can do it in XAML, or from code. In XAML it can only done by using a map control like this:

 <maps:MapControl x:Name="MyMap" MapServiceToken="Your mapkey goes here" />

By the way, the easiest way to get a map control on your app and get all the name spaces set up correctly is by dragging it onto the design surface, either in Visual Studio or in Blend.

The other way of getting this done is by using code.

Windows.Services.Maps.MapService.ServiceToken ="Your mapkey goes here" 

Put this for instance in the constructor in App.xamls.cs. If you have done it right, you won't see any of the pesky labels indicating you have an incorrect key. If it look like this:

... you might want back to square one and see what you missed.

A few things to consider / keep in mind

  • As far as I understand, you cannot reuse keys from earlier type of apps, even not when you are submitting a new version of an existing app that is already in the Store. You have to create a new one for your Windows 10 submission.
  • Bing maps keys are free for consumer-facing, education, and non-profit applications and for some business scenarios as well, but not in all cases, and not without limits. Be sure to study this page to make sure you create the right kind of key. If you are building a large enterprise app or an app that goes totally viral and pulls a lot of maps data, you might need an enterprise key and those are definitely not free.
  • Be aware of the fact that things like geocoding (finding an address based upon a location), reverse geocoding and routing also hit the map engine, so if you don't use a map but for instance want to do a simple 'find the ZIP code for this location app' you will need a Bing maps key as well. And unlike the map,that shows you a friendly warning that your MapServiceToken is not specified (like displayed above) but keeps functioning otherwise, the geocoding and routing api's simply will throw an exception when your key is not valid
  • If you come from Windows Phone 8.1, this may seem like the exact same control at first glance. It is not. Do not fall in that trap. It's a complete new control sitting in a new namespace:  Windows.UI.Xaml.Controls.Maps.MapControl

Stay tuned for more mapping. And get the sample app if you are impatient ;)

No comments: