# Upgrade Assistant binary analysis email to 1st parties

***TL;DR**: We plan on adding a binary analysis feature to Upgrade Assistant. This is
an early preview and we ask for your feedback.*

Hello esteemed first parties! 😊

Many of you have asked us to improve the analysis workflow when understanding
large existing code bases where starting directly with source code migration
isn't viable. In the past, we've pointed people to [API Port]. Unfortunately,
API Port is now a fairly dated tool, that originated in the .NET Core 1.0 days.
It has several problems, specifically that it doesn't understand which .NET
platform APIs are provided in-box in .NET Core/.NET Standard and which ones are
provided by NuGet packages.

We have decided that we're going to retire [API Port] and replace it by a binary
analysis feature that is built right into Upgrade Assistant. Based on your
feedback we believe it's not only the right place for the tool, it's also
providing valuable support in planning a larger migration by allowing you to
create an inventory of which binaries exist and how much work it would be to
port them to .NET Core and/or .NET Standard. We also want to add features that
enables tracking progress as you're migrating to .NET Core or are dual targeting
for .NET Framework and .NET Core.

At this state the binary analysis feature in Upgrade Assistant is in the early
stages which means a few features are still missing. However, we believe to have
implemented enough that you can take it out for a test ride and give us
feedback.

We're looking at feedback across the board, including

* the accuracy of the results
* the user experience of the tool
* how well the binary analysis fits into your migration workflow

## Binary analysis roadmap

We plan to have the following features in the binary analysis of Upgrade
Assistant:

| Feature | State | Description |
| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| Analyzing binaries | Implemented | Allows analyzing binaries for API usages of .NET platform APIs. |
| Offline support | Implemented | Allows the binary analysis to work in an environment without internet access. |
| Recommending packages | Implemented | Some .NET Framework APIs don't exist in .NET Core/.NET Standard directly but are made available as NuGet packages. |
| Detecting use of OS specific APIs | Implemented | Detects use of APIs that don't work on all OS platforms. |
| Detecting use of obsoleted APIs | Implemented | Detects use of APIs that have been obsoleted and might be removed or throw in future versions. |
| Detecting use of experimental APIs | Planned | Detects use of APIs that are experimental and might be changed or removed in future versions. |
| Exporting into a CSV file/Excel document | Planned | Exports the analysis results into a document that can be further edited or aggregated. |
| Checking against specific frameworks | Planned | Allows checking specific frameworks, rather than just `Current`, `LTS`, and `Preview`. |
| Checking migration status of binaries | Planned | Detects which binaries have been migrated to the target framework which is useful for producing progress reports. |

## Steps for installation

1. Download the [the preview build][UA-binary]
2. From the directory where you downloaded the the preview build to, run the
following command. Ensure to match the version of the preview build (in this case `0.4.0-dev`):

      dotnet tool update -g upgrade-assistant --add-source . --version 0.4.0-dev

Once installed, enable the binary analysis feature by setting the `UA_FEATURES`
environment variable to `ANALYZE_BINARIES`. In PowerShell, this would be:

$env:UA_FEATURES = 'ANALYZE_BINARIES'

Next, view the help for binary analysis in Upgrade Assisstant by running:

upgrade-assistant analyzebinaries -h

## Usage

Let's say you want to analyze all binaries in `D:\MyProject\bin`. This would
look like this:

upgrade-assistant analyzebinaries D:\MyProject\bin -t Current

Which would analyze all binaries in `D:\MyProject\bin` against the `Current`
version of .NET – at this time this is .NET 6.0. (LTS and Preview are also 6.0
as of this writing).

The output will be a SARIF file which is effectively JSON but can be opened in
Visual Studio as a set of analysis results using the [SARIF viewer extension][SARIF Viewer].

If you'd rather have output in HTML format, simply add `-f html` to the command:

upgrade-assistant analyzebinaries D:\MyProject\bin -t Current -f html

Looking forward to your feedback!

[API Port]: https://docs.microsoft.com/en-us/dotnet/standard/analyzers/portability-analyzer
[UA-binary]: https://aka.ms/ua-binary-preview
[SARIF Viewer]: https://marketplace.visualstudio.com/items?itemName=WDGIS.MicrosoftSarifViewer