A first hand look from the .NET engineering teams
Today we are happy to announce the alpha release of the .NET Portability Analyzer extension for Visual Studio. Please try it out. This add-in was created by our software developer intern Charles Lowell.
Over the last few years, consumers and enterprise employees are using more devices than before which run different operating systems like iOS, Android, Windows Phone, and Windows 8. As a result developing apps for different platforms is almost a requirement now. With the release of the .NET Portability Analyzer extension we are integrating the ability to reason about portability of your existing code into your development environment. This will allow you an easy way to understand how portable your code is and get recommendations to write your code so that your code just works across platforms.
You may have seen Tech Ed 2014 announcements & .NET blog post on “Targeting Multiple Platforms”. This post continues from there.
In our previous post we introduced the command line .NET Portability Analyzer. However, we felt that the acquisition and discovery of the tool for developers would be aided if we were to integrate the experience into VS. Additionally the integration into Visual Studio allows us to pinpoint the source locations where incompatible APIs are found to be. You can download it here. There is a great Channel 9 video about the extension which you can watch below.
Once you have installed the extension you can use the Portability Analyzer in two ways
This menu allows you to specify a set of libraries that you want to analyze and get a summary view of all the changes that would need to be made to make it compatible with a given platform.
The output of this analysis is a file that documents the overall compatibility of each assembly analyzed along with a detailed drill down into individual Types/Members that are missing and recommendations about how to fix them.
The project analysis adds a context menu to the project dialog, where you can request to analyze a given project for portability. The image below illustrates this experience.
When using this experience in addition to the report shown above, you will also get source level information about compatibility issue where available, which will be reported as a message in the error list of VS as shown below.
Using the API Portability Analyzer extension will enable you to get a quick overview of all the changes that you would need to make in order to be able to port your code to a given platform. Given the assembly level break-down it enables you to easily prioritize and cost either the easiest ports or the most high value ports depending on your business requirements. We are actively working on the recommendations to make them actionable and informative.
In case you don`t have VS or wanted to integrate this functionality into your build the API Portability Analyzer tool takes your existing app or library and provides a report which tells you how compatible you are with different platforms. Let’s take a quick look into how you could use the API Portability Analyzer. Download the tool from the site above and run the command as follows:
This command will analyze the Autfac libraries and give you a report Excel file, which summarizes the compatibility of the existing Autofac binaries against the different platform profiles.
We see that the assembly for Autofac is fully compatible with Silverlight and there are some missing dependencies for the Autofac.Configuration dll. If we wanted to drill into this further you can look at the details page in the excel sheet and see a view as follows.
The details page gives us information about the specific members that are missing from a type and recommendations around alternatives that can be used. We are actively working to fill out the recommendations for the missing APIs so that you have guidance around how you can move your code over to a given platform. You can use your inner Excel ninja to get different organizations around the work that needs to be done in order to move to a given platform. Remember pivot-tables are your friend.
The API Portability Analyzer submits anonymous data to Microsoft about the .NET APIs used by your app. This aggregate data provides input to us on popular and missing APIs along with understanding where our customers are currently trying to migrate code from. As we work on our next set of features and compatibility reviews, this would help us spend more time on enabling APIs that you love and use most frequently. For instance based on the data, we are now working on enabling TypeConverter and System.Web types on the ASP.NET vNext K stack. The information that we collect is the .NET APIs that your app is using, along with some other metadata like what framework version your assembly was built against and assembly references of your assembly. The dotnetstatus site gives you a visual sense of the data that we are collecting and we are looking at ways to add more value to this site. Your feedback around what features or data you would like to see here would be appreciated.
Using this tool enables you to quickly get a high level understanding of the work that needs to be done to port to a given platform. While it may appear that you would need to do work every time that you want to target a new platform, we on the .NET framework team are working to enable a vision of single .NET surface area. Our goal is to have parity across the APIs that we expose on our Modern framework stacks. The only reason for a missing API would be its lack of applicability to a given application model or platform. The introduction of the Visual Studio extension makes it easy to reason about the migrating of code to a new platform. Depending on what your business requirements are you can easily prioritize and understand the costs of supporting a new platform. In addition this tool give us insights into the biggest pain points that you face when migrating your code. We would love to hear your feedback on how to make this tool better! Please let us know what you think by either leaving a comment on this post or reaching out to the team at NETAPIPort@Microsoft.com.
Did I just see you support ASP.NET vNext as well? Thank you so much, this will help so many people test and plan for the future!
Any chance this is extensible and a mono check could also be added?
@Mladen Mono is also supported along with MonoAndroid and MonoTouch.
We at the company have a proxy. It seems that the tool attempts to connect to a web service. Our proxy blocks the request.
Could you tell us what is the URL of the service to enable a rule in the Proxy?.
Thank you very much.
When will the XNA compatibility will be implemented in this tool?
I'd like to know more about Mono and versions in general. For example, the analyzer reports "Mono 4.5", but the last mono release is 3.4. So, I guess it is referring to ".net 4.5 on mono", but then, which version of mono is it testing against?
I believe we could assume "latest" for any, but would be nice to know exactly what we are testing against. The same could go for vNext. Does it work on nightly builds of the git repository? When is it updated?
Hope you guys post more details about how the analysis is done, how do you obtain the metadata and what kind of check is made (for example, you only check the existence of methods in mono dlls or do you do something else?)
Would also be nice to support multiple versions of frameworks, including previous versions of both for Mono and .NET. So, for example, I may not only be interested in running my app in Mono, but I want to know if I can run on a server with mono 3.2 which is not the latest. The same goes for a library that may now require .NET 4.5, but a few changes or IFDEFs would make the same code run on 2.0 or 4.0.
Mono: awesome news! Natan does have some valid questions though ☺
@Francisco Suarez the service is located at portability.cloudapp.net hope this helps.
What does Mono 4.5 mean?
This was intended to map to .NET Framework version 4.5. We are working on updating this to match Mono`s versions.
What does latest mean?
For released platforms it is the latest released version. For platforms that are currently in development, like ASP.NET vNext, we update the service weekly.
How is the analysis done?
We collect the APIs that your assemblies use and cross-reference them against the APIs that are present in the targets that you specify.
Can I target multiple versions of the framework?
You can do this via the command line tool. www.microsoft.com/.../details.aspx.
Here is how you do it:
ApiPort.exe "-targets:.NET Framework,Version=3.5;.NET Framework,Version=1.1" <assemblies> .
This is a great feature enhancement and we are working on a way to expose this better in both the command line tool and the extension.
Thanks for the quick response Alok.
I just downloaded the ApiPort.exe and was testing it. Looks like you have it all covered.
I guess you are probably already working on it, but:
1. -listTargets only lists the framework, doesn't list the version (as you mentioned, just need to expose more info)
2. If you pass an invalid framework, it just uses the default. This is strange because I was hoping it would complain it couldn't test against that version or something, instead it reports like you didn't pass anything. This would be useful even for you to get info on bad queries and see things people are trying to check against that may not be implemented.
3. It would be nice to output an html by default just as you did in VS. We don't always have excel installed.
Also, is this on codeplex/github/anywhere else?
Even if the source is not available, it would be useful to have a location to report issues, discuss and check the status of the tool. I'm very interested as I have started to develop services I need to run on mono/linux and this tool came in the right time.
Two things I noticed about the Extension(Reported on the Extension Page):
1.) It seems this extension ignores the build configuration(always uses AnyCPU, even if you have x86/x64 selected in VS), when you use the analyze function from the project context menu.
2.) The Analyze context menu entry is also present in unloaded projects.
"1. -listTargets only lists the framework, doesn't list the version (as you mentioned, just need to expose more info"
Yup we are working to fix that that right now :)
"2. If you pass an invalid framework, it just uses the default"
will take a look at that. What did you pass in ?
"3. HTML default"
Interesting point can definitely consider this
"4. Reporting Issues:"
You can reach out to us at NETAPIPort@Microsoft.com or leave a comment here.
Was tring some different versions.
apiport -targets:Mono,Version=4.5 Assembly.dll
This ignores the argument and returns "asp.net vnext, windows, .net, silverlight, windows phone":
apiport -targets:Mono,Version=3.4 Assembly.dll
Would it be possible for the tool to support mono as a runtime option i.e. can you make the tool run on Mono. I use Linux with Mono and would still want to use the tool.
Looks like this is a mono issue, as it doesn't implement GzipStream(Stream,CompressionLevel) overload yet. Maybe just using the other overload would work. github.com/.../GZipStream.cs
It will work like that. That is what ASP.NET vNext does.