Writing mappings for project references

By default the conversion tool removes references unknown to assemblies or NuGet packages . In order to keep or update references, the tool provides a mechanism for specifying the way to convert assembly references.

##Create a mapping from a NuGet reference to another NuGet package

Some NuGet packages referenced in Windows Phone 8 projects may not work on UWP. The tool allows the creation of mappings for NuGet references.

For example the NuGet for LumiaImagingSDK need to be updated to a version that works with UWP. In order to do that we can write the following mapping:

<ReferenceMap Id="LumiaImagingSDK"
              xmlns="clr-namespace:Mobilize.Mappers.Extensibility.References;assembly=Mobilize.ExtensibleMappers">
  <ReferenceMap.Obsolete>
    <Nuget Id="LumiaImagingSDK">
      <Assembly Name="Lumia.Imaging"/>
    </Nuget>
  </ReferenceMap.Obsolete>
  <ReferenceMap.New>
    <Nuget Id="LumiaImagingSDK.UWP" Version="3.0.593" >
      <Assembly Name="Lumia.Imaging"/>
    </Nuget>
  </ReferenceMap.New>
</ReferenceMap>

The ReferenceMap.Obsolete element property specify the NuGet reference to change. This tag has to include the assemblies added by the NuGet package, in this case Lumia.Imaging. The ReferenceMap.New specify the references to add to the target project. In this case we add the reference to the LumiaImagingSDK.UWP package.

##Converting Between SDKReferences

SDKReferences, or references added to the CSPROJ project using the SDKReference tag can be converted to a supported UWP reference . For example, Live SDK references need to be updated to the 5.6 version of the SDK (this also requires manually installing this version of the Live SDK). The mapping looks like this:

<ReferenceMap Id="Microsoft.Live"
              xmlns="clr-namespace:Mobilize.Mappers.Extensibility.References;assembly=Mobilize.ExtensibleMappers">
  <ReferenceMap.Obsolete>
    <SDKReference Name="LiveSDK_RTSL"></SDKReference>
  </ReferenceMap.Obsolete>
  <ReferenceMap.New>
    <SDKReference Name="LiveSDKXAML" Version="5.6" />
  </ReferenceMap.New>
</ReferenceMap>

##Converting between different kinds of references

The conversion of project references could be specified between different kinds. For example a references to System.Windows.Interactivity may be converted to an SDKRefeference to BehaviorsXamlSDKManaged . For example:

<ReferenceMap Id="Behaviors"
              xmlns="clr-namespace:Mobilize.Mappers.Extensibility.References;assembly=Mobilize.ExtensibleMappers">
  <ReferenceMap.Obsolete>
    <Assembly Name="System.Windows.Interactivity"></Assembly>
  </ReferenceMap.Obsolete>
  <ReferenceMap.New>
    <SDKReference Name="BehaviorsXamlSDKManaged" Version="12.0"  />
  </ReferenceMap.New>
</ReferenceMap>

#Obsolete references

A Windows Phone Silverlight project may contain references to other assemblies that either need to be removed or changed to another reference.

For example if we want to remove the reference to the Microsoft.Phone.Control.Maps.dll assembly .

When converting this application the resulting project will have a reference to the same assembly (now missing):

To remove this reference as part of the migration process we can add a .refmap file to the %LOCALAPPDATA%\Mobilize.NET\Mappings directory. We can name this file Maps.refmap .

<ReferenceMap Id="Microsoft.Phone.Controls"
             xmlns="clr-namespace:Mobilize.Mappers.Extensibility.Projects;assembly=Mobilize.ExtensibleMappers">

 <ReferenceMap.Obsolete>
   <Assembly Name="Microsoft.Phone.Controls.Maps" />
 </ReferenceMap.Obsolete>

</ReferenceMap>