Skip to content

Introduction to mappings

ldfallas edited this page Sep 11, 2015 · 4 revisions

What is a mapping?

A mapping is a small specification of how to convert an API from a one platform to another.

How mappings are defined by the conversion tool?

The Windows Phone Silverlight to UWP conversion tool defines mappings as a series of actions to be taken for each use of a member of a class.

The conversion tool keeps a collection of tables which contain the list of actions for each API it supports. For example, the following tables show the mappings for the Microsoft.Phone.Controls.Maps.Map control and for the System.Device.Location.GeoCoordinate class:

Microsoft.Phone.Controls.Maps.Map

Kind Member name Action
Type reference N/A Replace type reference with Windows.UI.Xaml.Controls.Maps.MapControl
Method call SetView Replace the call to SetView with a call to TrySetViewAsync also invoke it using await

System.Device.Location.GeoCoordinate

Kind Member name Action
object instantiation N/A Replace constructor call with a call to Windows.Devices.Geolocation.Geopoint with a new instance of Windows.Devices.Geolocation.BasicGeoposition with the Latitude and Longitude set to the arguments of the original constructor invocation.

These are known as the mapping tables.

How mappings are applied to the input project?

Mappings are applied by executing a tree traversal process on the abstract syntax tree of C# code of the input project.

While performing the tree traversal the mapping tables (see above) are used to verify if the current element requires an action to be applied.

Here's a simplified execution of the mapping process using the mappings described in the previous topic:

Step 0

We start with a the AST of a C# file from the input project:

step 0

Step 1

The tree traversal starts by visiting the declaration of the MyMap property, this property has a type Microsoft.Phone.Controls.Maps.Map.

step 1

If we look into our mapping tables we find that there's mapping for the type reference for this source type Microsoft.Phone.Controls.Maps.Map . Then we apply the action specified in the mapping table, which says that we have to replace the type reference by the Windows.UI.Xaml.Controls.Maps.MapControl class.

After performing this change, the traversal process is resumed.

Step 2

The next stop in our tree traversal process is the object instantiation expression of the System.Device.Location.GeoCoordinate class.

step 2

If we look into our mapping table we see that we need to convert it to an instantiation of Windows.Devices.Geolocation.Geopoint with some extra details described above.

After performing this change, the traversal process is resumed.

Step 3

Our next stop in our tree traversal process is the call to the Microsoft.Phone.Controls.Maps.Map.SetView method.

step 3

If we look into our mapping tables, we can see that it specifies that the conversion tool to replace the method call with a call to TrySetViewAsync with an await modifier.

After performing this change, the traversal process is resumed.

Step 4

The next stop in our tree traversal process is the call to the System.Diagnostics.Debug.WriteLine method.

step 4

If we look into our mapping tables we can see there's no mapping for this API, so the conversion tool will keep it unchanged.

Step 5

Since there are no more elements to inspect, the traversal process stops. An additional process will make sure that awaited methods are invoked inside method with the async modifiers.

step 5

Overview

Writing mappings

Code Mapping Actions

Code Mapping Conditions

XAML mapping actions

XAML mapping conditions

Misc

Clone this wiki locally