-
Notifications
You must be signed in to change notification settings - Fork 5
Introduction to mappings
A mapping is a small specification of how to convert an API from a one platform to another.
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.
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 1
The tree traversal starts by visiting the declaration of the MyMap
property, this property has a type Microsoft.Phone.Controls.Maps.Map
.
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.
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.
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.
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.
Contact us for more information
Overview
Writing mappings
Code Mapping Actions
- ActionSequence
- AddHelper
- AddNamespaceImport
- AddPreStatementFromTemplate
- CommentOut
- Conditional
- Keep Code Mapping Action
- MarkAsNotMapped
- RedirectCall
- RedirectCallToInnerMember
- RedirectIndexer
- RedirectProperty
- RemoveCurrentStatement
- RemoveParameter
- ReplaceClassUsage
- ReplaceMethodBodyWithTemplate
- ReplaceParameterDeclarationType
- ReplaceParameterMember
- ReplaceParameterValue
- ReplaceWithMethodCall
- ReplaceWithProperty
- ReplaceWithTemplate
Code Mapping Conditions
- AllConditionsApply
- ArgumentCount
- AssignName
- AssignNameToArgumentRange
- IsExpressionOfType
- IsStringLiteralMatchingRegex
- WithArgument
- WithAssignment
- WithAssignmentLeftSide
- WithAssignmentRightSide
- WithCalledMemberOwner
- WithCalledMethodExpression
- WithConstructorCall
- WithLambdaExpressionBody
- WithLambdaExpressionParameter
- WithLeftSideOfDottedAccess
- WithMemberInitValue
- WithMethodCall
XAML mapping actions
- ActionSequence
- AddStatementToConstructorFromTemplate
- BindPropertyValueElement Xaml mapping action
- ChangeEventHandlerEventArgsType
- CommentOutElement
- CommentOutProperty
- MarkAsNotMapped
- MoveValueToContentProperty
- RemoveNamespaceDeclaration
- RenameElement
- RenameProperty
- ReplaceAttributeValue
- ReplaceEventHandlerBodyWithTemplate
- ReplaceEventHandlerParameterMember
- ReplaceNamespaceDeclaration
- ReplacePropertyValueWithParentResource
- ReplaceStaticResourceWithThemeResource
- SetPropertyValueToComplexElement
- SetPropertyValueToSimpleValue
- WrapContent
XAML mapping conditions
Misc