diff --git a/README.md b/README.md
index 726bb82a6..342f3195d 100644
--- a/README.md
+++ b/README.md
@@ -3,43 +3,40 @@
This repository contains the source code for .NET Portability Analyzer tools and
dependencies.
-## Usage
+| Status | Latest Version |
+| :----- | :------------- |
+| ![][BuildStatus] | [![][Version]][myget] |
-To use this tool, please refer to the [documentation](docs/HowTo/Introduction.md).
For a quick introduction, check out [this video on Channel 9][Channel 9 Video]:
[
][Channel 9 Video]
-## Projects
-
-| Project | Description |
-| :------- | :----------- |
-| ApiPort | Console tool to access portability webservice |
-| ApiPort.Core | Cross-platform .NET Core application |
-| ApiPort.Vsix | Visual Studio Extension |
-| Microsoft.Fx.Portability [![][Version-Portability]][myget] | Provides common types for API Port |
-| Microsoft.Fx.Portability.MetadataReader [![][Version-MetadataReader]][myget] | Implements a dependency finder based off of [System.Reflection.Metadata](https://github.com/dotnet/corefx/tree/master/src/System.Reflection.Metadata). The library will generate DocIds that conform to [these specifications](https://msdn.microsoft.com/en-us/library/fsbx0t7x.aspx). |
-| Microsoft.Fx.Portability.Offline [![][Version-Offline]][myget] | Provides access to data in an offline setting so network calls are not needed |
-| Microsoft.Fx.Portability.Reporting.Html [![][Version-Reporting Html]][myget] | Provides an HTML report for ApiPort (used in offline mode) |
-| Microsoft.Fx.Portability.Reporting.Json [![][Version-Reporting Json]][myget] | Provides a JSON reporter for ApiPort (used in offline mode) |
-
## Using this Repository
* Install [Visual Studio 2015 with Update 3][Visual Studio 2015]
+* Install [.NET Core 1.0.1](https://dot.net/core)
-### ApiPort.Core
-
-__Prerequisites__
+## Documentation
-* Install [.NET Core 1.0.1](https://dot.net/core)
+* [Introduction](docs/HowTo)
+* [Platform Portability](docs/HowTo/PlatformPortability.md)
+* [Breaking Changes](docs/HowTo/BreakingChanges.md)
+* [.NET Portability Analyzer (Console application)](docs/Console)
+ * [.NET Core application](docs/Console/README.md#using-net-core-application)
+* [.NET Portability Analyzer (Visual Studio extension)](docs/VSExtension)
-__Compiling, Debugging and Running__
+## Projects
-* Change __Platform__ to `x64`
-* Compile solution
-* Run/debug the solution by:
- * Executing: `dotnet.exe ApiPort.exe [arguments]`
- * Debug `ApiPort.Core` project in Visual Studio
+| Project | Description |
+| :------ | :---------- |
+| ApiPort | Console tool to access portability webservice |
+| ApiPort.Core | Cross-platform .NET Core application |
+| ApiPort.Vsix | Visual Studio Extension |
+| Microsoft.Fx.Portability | Provides common types for API Port |
+| Microsoft.Fx.Portability.MetadataReader | Implements a dependency finder based off of [System.Reflection.Metadata][System.Reflection.Metadata]. The library will generate DocIds that conform to [these specifications][DocId]. |
+| Microsoft.Fx.Portability.Offline | Provides access to data in an offline setting so network calls are not needed |
+| Microsoft.Fx.Portability.Reporting.Html | Provides an HTML report for ApiPort (used in offline mode) |
+| Microsoft.Fx.Portability.Reporting.Json | Provides a JSON reporter for ApiPort (used in offline mode) |
## How to Engage, Contribute and Provide Feedback
@@ -61,7 +58,7 @@ for more details.
* [How to Contribute][Contributing Guide]
* [Contributing Guide][Contributing Guide]
- * [Developer Guide]
+ * [Developer Guide][Developer Guide]
You are also encouraged to start a discussion on the .NET Foundation forums!
@@ -74,17 +71,16 @@ For an overview of all the .NET related projects, have a look at the
This project is licensed under the [MIT license](LICENSE).
+[BuildStatus]: https://devdiv.visualstudio.com/_apis/public/build/definitions/0bdbc590-a062-4c3f-b0f6-9383f67865ee/484/badge
[Channel 9 Video]: https://channel9.msdn.com/Blogs/Seth-Juarez/A-Brief-Look-at-the-NET-Portability-Analyzer
[Contributing Guide]: https://github.com/dotnet/corefx/wiki/Contributing
[Developer Guide]: https://github.com/dotnet/corefx/wiki/Developer-Guide
+[DocId]: https://msdn.microsoft.com/en-us/library/fsbx0t7x.aspx
[Issues-Open]: https://github.com/Microsoft/dotnet-apiport/issues?q=is%3Aopen+is%3Aissue
[PR]: https://github.com/Microsoft/dotnet-apiport/pulls
[PR-Closed]: https://github.com/Microsoft/dotnet-apiport/pulls?q=is%3Apr+is%3Aclosed
[PR-Open]: https://github.com/Microsoft/dotnet-apiport/pulls?q=is%3Aopen+is%3Apr
[myget]: https://www.myget.org/gallery/dotnet-apiport
-[Version-Portability]: https://img.shields.io/myget/dotnet-apiport/v/Microsoft.Fx.Portability.svg
-[Version-MetadataReader]: https://img.shields.io/myget/dotnet-apiport/v/Microsoft.Fx.Portability.MetadataReader.svg
-[Version-Offline]: https://img.shields.io/myget/dotnet-apiport/v/Microsoft.Fx.Portability.Offline.svg
-[Version-Reporting Html]: https://img.shields.io/myget/dotnet-apiport/v/Microsoft.Fx.Portability.Reports.Html.svg
-[Version-Reporting Json]: https://img.shields.io/myget/dotnet-apiport/v/Microsoft.Fx.Portability.Reports.Json.svg
+[System.Reflection.Metadata]: https://github.com/dotnet/corefx/tree/master/src/System.Reflection.Metadata
+[Version]: https://img.shields.io/myget/dotnet-apiport/v/Microsoft.Fx.Portability.svg
[Visual Studio 2015]: http://www.visualstudio.com/en-us/downloads/visual-studio-2015-downloads-vs.aspx
\ No newline at end of file
diff --git a/docs/Console/README.md b/docs/Console/README.md
new file mode 100644
index 000000000..7d3654cbc
--- /dev/null
+++ b/docs/Console/README.md
@@ -0,0 +1,171 @@
+# .NET Portability Analyzer (Console application)
+
+The console tool helps you determine how flexible your application. The tool
+understands the following commands:
+
+ * `ApiPort.exe analyze `
+ * Analyzes the portability of an application
+ * [Examples](#apiportexe-analyze-scenarios)
+ * `ApiPort.exe listTargets`
+ * Lists .NET platforms available for analysis
+ * `ApiPort.exe listOutputFormats`
+ * Lists available report output formats
+ * `ApiPort.exe DocIdSearch `
+ * Searches for matching docIds
+
+## `ApiPort.exe analyze` Scenarios
+
+Arguably the most important function of the tool is its ability to analyze an
+assembly. This can take in a file, collection of files, or a directory of
+assemblies.
+
+**Analyzing a file against specific targets and outputting an HTML report**
+
+```
+ApiPort.exe analyze -f Foo.dll -t ".NET Framework, Version=4.6.2" -t
+".NET Standard, Version=1.6" -r HTML -o AnalysisReport.html
+```
+
+The `-f` flag followed by a path represents the file or directory that the
+analysis should be performed on; in this case, it is `Foo.dll`. The multiple
+uses of `-t` followed by target names tells the tool what .NET platforms we want
+to analyze the input assembly(ies) against. `-r` is the output format of the
+report. `-o` is the output name for that report.
+
+So, our analysis will be performed on `Foo.dll` against
+`.NET Framework, Version=4.6.2` and `.NET Standard, Version=1.6` and output as
+an HTML file, `AnalysisReport.html`.
+
+**Analyzing a directory against the default targets and outputting default
+report format**
+
+```
+ApiPort.exe analyze -f C:\git\Application\bin\Debug
+```
+
+This will analyze all assemblies that exist under `C:\git\Application\bin\Debug`
+recursively, and analyzes those assemblies against the default .NET platforms.
+(**Note:** The default platforms can be obtained by running `ApiPort.exe
+listTargets` and looking for targets that have an (\*) in them.)
+
+**Analyzing a directory and show breaking changes**
+
+```
+ApiPort.exe analyze -f C:\git\Application\bin\Debug -b
+```
+
+The `-b` flag will show any APIs that may have different behavior between
+versions of .NET Framework due to breaking changes that have been made. The
+entire list of breaking changes in .NET Framework can be found by examining
+[Application Compatibility in the .NET Framework][Breaking Changes]. For the
+list of breaking changes we analyze against, look [here](BreakingChanges.md).
+
+**Analyzing a directory and show any non-portable APIs**
+
+```
+ApiPort.exe analyze -f C:\git\Application\bin\Debug -p
+```
+
+The `-p` flag will highlight any APIs that are not portable against the default
+target .NET platforms. (No explicit `-t` arguments were specified, so we use the
+default targets.)
+
+## Using .NET Core application
+
+The portability analyzer has a version that targets .NET Core. Possible reasons
+for using the .NET Core application include:
+
+* Working on machine without .NET Framework 4.6 installed
+* Working on a non-Windows OS
+
+### Compiling, Debugging and Running
+
+**From Commandline**
+
+1. Execute `build.cmd`
+2. Go to `bin\Release\ApiPort.Core\netcoreapp1.0`
+3. Go to either `x64` or `x86` folder
+4. Execute `dotnet.exe ApiPort.exe`
+
+**In Visual Studio 2015**
+
+1. Change **Platform** to `x64` or `x86`
+2. Compile solution
+3. Set `ApiPort.Core` as Start-up Project
+4. Start debugging (F5)
+
+### Troubleshooting
+
+**Problem: The program can't start because api-ms-win-crt-runtime-l1-1-0.dll is missing
+from your computer.**
+
+Solution: Install [Visual Studio 2015 C++ Redistributable][VS2015 C++ Redistributable].
+
+## Alternate modes
+
+The tool by default will gather the results and submit to a webservice that will
+analyze the data to determine which APIs need to be addressed. For full details
+on this process, please read the [privacy policy][Privacy Policy]. There are
+two alternate modes that can be used to alter this workflow.
+
+### See the data being transmitted
+
+The first option is to output the request to a file. This will result in an
+output that shows what data is being transmitted to the service, but provides no
+details as to API portability or breaking changes. This is a good option if you
+would like to see what data will be collected.
+
+In order to enable this mode, create a file `unity.config` and place it in the
+same directory as `ApiPort.exe`. Add the following contents:
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+Now, when you run, it will output a file with the information that is sent to
+the .NET Portability service.
+
+### Run the tool in an offline mode
+
+Another option is to enable full offline access. This mode will not get
+automatic updates and no official releases of it are available. In order to use
+this mode, the solution must be manually built. To do so, please follow these
+steps:
+
+1. Clone the project: `git clone https://github.com/Microsoft/dotnet-apiport`
+2. Build the project: `build.cmd`.
+
+ *Note: This command must be used as it gathers the correct assemblies for offline mode. Building in VS does not do this.*
+
+3. Go to `bin\release\ApiPort.Offline`
+4. Run `ApiPort.exe` from this directory as normal.
+
+Additional reports can be generated in offline mode. Any implementation of
+`Microsoft.Fx.Portability.Reporting.IReportWriter` can be used. Add an entry to
+`unity.config` following the pattern of the HTML and json writers. The offline
+mode will pick it up and allow reports to be returned in custom formats.
+
+Note that offline mode is not supported for .NET Core versions of ApiPort.
+
+[Breaking Changes]: https://msdn.microsoft.com/en-US/library/dn458358(v=vs.110).aspx
+[Issue #2311]: https://github.com/dotnet/cli/issues/2311
+[Privacy Policy]:/docs/LicenseTerms/Microsoft%20.NET%20Portability%20Analyzer%20Privacy%20Statement.txt
+[VS2015 C++ Redistributable]: https://www.microsoft.com/en-us/download/details.aspx?id=53587
\ No newline at end of file
diff --git a/docs/DocImages/FalseErrors.png b/docs/DocImages/FalseErrors.png
deleted file mode 100644
index 908c7b9aa..000000000
Binary files a/docs/DocImages/FalseErrors.png and /dev/null differ
diff --git a/docs/HowTo/Introduction.md b/docs/HowTo/Introduction.md
deleted file mode 100644
index dd7ccbb1f..000000000
--- a/docs/HowTo/Introduction.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# Introduction
-
-This repository holds a collection of tools for analyzing assemblies targeting the .NET Framework. As the .NET Framework
-has grown, there has been a number of pain points in moving between supported platforms and versions. The goal of these
-tools is to help identify possible problem areas in an assembly and help direct targeted testing, by identifying APIs that:
-
-1. Are not portable to specific platforms
-2. Have breaking changes between 4.x versions
-
-For a quick introduction, check out [this video on Channel 9](https://channel9.msdn.com/Blogs/Seth-Juarez/A-Brief-Look-at-the-NET-Portability-Analyzer):
-
-[](https://channel9.msdn.com/Blogs/Seth-Juarez/A-Brief-Look-at-the-NET-Portability-Analyzer)
-
-## Platform Portability
-
-The first goal of these tools are to help identify APIs that are not portable among the various .NET Platforms. These
-include Microsoft supported platforms (Windows, Windows apps, DNX) as well as other implementations, such as Mono and
-Xamarin. Some APIs may be removed on certain platforms (such as AppDomains, File I/O, etc), or refactored into other
-types (such as some Reflection APIs). Sometimes the fix will be relatively simple while other times it may be more involved.
-This tool provides information to help guide a developer to rework or rewrite certain parts of an assembly to be more portable
- and resilient to version changes. For details please see [here](PlatformPortability.md).
-
-## Breaking Changes between .NET 4.x versions
-
-Another goal of the tools is to provide guidance and insight into possible breaking changes on the .NET Framework that may
-apply to a given assembly. This functionality is currently restricted to .NET Framework 4.x given that it is updated in-place
-with no side-by-side support for alternative versions. Most of these are considered benign changes that shouldn't affect
-most applications; however, we understand that what may be low impact for one scenario may be a very impactful breaking change
-for another. For details please see [here](BreakingChanges.md).
-
-# Usage
-
-The tools are available as a command line tool, a VS plugin, as well as a collection of libraries. The VS plugin is updated at
-a slower pace than the command line tool (for instance, it currently does not support the breaking change functionality). The
-command line tool is available at [github](http://github.com/microsoft/dotnet-apiport/releases), and requires .NET 4.5 or Mono
-(there is a [work item](https://github.com/Microsoft/dotnet-apiport/issues/117) to convert this to a DNX application).
-
-The tool understands three commands:
-
-### Analyze
-
-Arguably the most important function of the tool is its ability to analyze an assembly. This can take in a file, collection of
-files, or a directory of assemblies.
-
-`ApiPort.exe analyze `
-
-The current options are:
-
-```
- -f, --file=VALUE [Required] Path to assembly file or directory of
- assemblies.
- -o, --out=VALUE Output file name
- -d, --description=VALUE Description of the submission
- -t, --target=VALUE The target you want to check against.
- -r, --resultFormat=VALUE The report output format
- -p, --showNonPortableApis Calculate non-portable APIs
- -b, --showBreakingChanges Calculate breaking changes on full .NET Framework
- -u, --showRetargettingIssues Include the retargetting issues in the reports
- --noDefaultIgnoreFile Do not use the standard assembly ignore list
- when analyzing breaking changes. The default
- ignore list can be found at KnownSafeBreaks.json
- -i, --ignoreAssemblyFile=VALUE
- Specifies a json file defining assemblies that
- should not be analyzed for specific targets
- while analyzing breaking changes. This can be
- useful for excluding assemblies that are known
- to not regress on certain .NET Framework
- versions due to breaking changes. Note that,
- currently, this parameter only affects breaking
- change analysis; not portability analysis.
- -s, --suppressBreakingChange=VALUE
- Specifies a breaking change (by ID) to suppress
- during breaking change analysis. Any breaking
- changes with IDs specified for suppression will
- not be reported.
- -h, -?, --help Show help
-```
-
-For more details on analysis for portability look [here](PlatformPortability.md). For breaking change analysis please
-look [here](BreakingChanges.md).
-
-For example, to analyze `foo.dll` against `.NET Core` and the latest `.NET Framework` and get an HTML report, the following command would be run:
-
-```
-ApiPort.exe analyze -f foo.dll -t ".NET CORE, Version=5.0" -t ".NET Framework" -r HTML
-```
-
-### List targets
-
-The targets available to analyze against are retrieved from a service that is updated regularly. These targets change over time as new
-platforms are available. The service will default to the most current platforms and versions.
-
-For example, the command `ApiPort.exe listTargets` will output:
-
-```
-Available Targets:
-- .NET Core [Version: 5.0*]
-- .NET Core (Cross-platform) [Version: 5.0]
-- .NET Framework [Version: 1.1; 2.0; 3.0; 3.5; 4.0; 4.5; 4.5.1; 4.5.2; 4.6; 4.6.1*]
-- .NET Native [Version: 1.0*]
-- ASP.NET 5 [Version: 1.0*]
-- Mono [Version: 3.3.0.0]
-- Silverlight [Version: 2.0; 3.0; 4.0; 5.0]
-- Windows [Version: 8.0; 8.1]
-- Windows Phone [Version: 8.1]
-- Windows Phone Silverlight [Version: 7.0; 7.1; 8.0; 8.1]
-- Xamarin.Android [Version: 4.12.1]
-- Xamarin.iOS [Version: 7.2.2]
-
-Available Grouped Targets:
-- Mobile (Windows, Windows Phone, Xamarin.Android, Xamarin.iOS)
-
-Notes on usage:
-- In order to specify a version, please use the following format with the '-targets' option:
- (Target Name), Version=(Version)
-
-- Versions marked with an asterisk (*) implies that these are default targets if none are submitted.
-```
-
-Any combination of these can be supplied to the `analyze` command with the `-t` option.
-
-### List output formats
-
-The output formats available for the results can be retrieved with `ApiPort.exe listOutputFormats`. This currently
-results in the following output formats:
-
-- json
-- HTML
-- Excel
-
-# Alternate modes
-
-The tool by default will gather the results and submit to a webservice that will analyze the data to determine which APIs need to be addressed. For full
-details on this process, please read the [privacy policy](/docs/LicenseTerms/Microsoft%20.NET%20Portability%20Analyzer%20Privacy%20Statement.txt).
-There are two alternate modes that can be used to alter this workflow.
-
-## See the data being transmitted
-
-The first option is to output the request to a file. This will result in an output that shows what data is being transmitted to the service, but provides
-no details as to API portability or breaking changes. This is a good option if you would like to see what data will be collected.
-
-In order to enable this mode, create a file `unity.config` and place it in the same directory as `ApiPort.exe`. Add the following contents:
-
-```xml
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-```
-
-Now, when you run, it will output a file with the information that is sent to the .NET Portability service.
-
-## Run the tool in an offline mode
-
-Another option is to enable full offline access. This mode will not get automatic updates and no official releases of it are available. In order to use this mode,
-the solution must be manually built. To do so, please follow these steps:
-
-1. Clone the project: `git clone https://github.com/Microsoft/dotnet-apiport`
-2. Build the project: `build.cmd`.
-
- *Note: This command must be used as it gathers the correct assemblies for offline mode. Building in VS does not do this.*
-
-3. Go to `bin\release\ApiPort.Offline`
-4. Run `ApiPort.exe` from this directory as normal.
-
-Additional reports can be generated in offline mode. Any implementation of `Microsoft.Fx.Portability.Reporting.IReportWriter` can be used. Add an entry to `unity.config`
-following the pattern of the HTML and json writers. The offline mode will pick it up and allow reports to be returned in custom formats.
-
-Note that offline mode is not yet supported for .NET Core (CoreCLR) versions of ApiPort.
diff --git a/docs/HowTo/README.md b/docs/HowTo/README.md
new file mode 100644
index 000000000..463cbd981
--- /dev/null
+++ b/docs/HowTo/README.md
@@ -0,0 +1,31 @@
+# Introduction
+
+This repository holds a collection of tools for analyzing assemblies targeting the .NET Framework. As the .NET Framework
+has grown, there has been a number of pain points in moving between supported platforms and versions. The goal of these
+tools is to help identify possible problem areas in an assembly and help direct targeted testing, by identifying APIs that:
+
+1. Are not portable to specific platforms
+2. Have breaking changes between 4.x versions
+
+## Platform Portability
+
+The first goal of these tools are to help identify APIs that are not portable among the various .NET Platforms. These
+include Microsoft supported platforms (Windows, Windows apps, DNX) as well as other implementations, such as Mono and
+Xamarin. Some APIs may be removed on certain platforms (such as AppDomains, File I/O, etc), or refactored into other
+types (such as some Reflection APIs). Sometimes the fix will be relatively simple while other times it may be more involved.
+This tool provides information to help guide a developer to rework or rewrite certain parts of an assembly to be more portable
+ and resilient to version changes. For details please see [here](PlatformPortability.md).
+
+## Breaking Changes between .NET 4.x versions
+
+Another goal of the tools is to provide guidance and insight into possible breaking changes on the .NET Framework that may
+apply to a given assembly. This functionality is currently restricted to .NET Framework 4.x given that it is updated in-place
+with no side-by-side support for alternative versions. Most of these are considered benign changes that shouldn't affect
+most applications; however, we understand that what may be low impact for one scenario may be a very impactful breaking change
+for another. For details please see [here](BreakingChanges.md).
+
+## .NET Portability Analyzer Tools
+
+* [Console Application (.NET Framework)](../Console)
+* [.NET Core Application](../Console/README.md#using-net-core-application)
+* [Visual Studio 2015 Extension](../VSExtension)
\ No newline at end of file
diff --git a/docs/VSExtension/README.md b/docs/VSExtension/README.md
index e4e89e85f..017ed5129 100644
--- a/docs/VSExtension/README.md
+++ b/docs/VSExtension/README.md
@@ -1,7 +1,5 @@
# .NET Portability Analyzer (Visual Studio Extension)
-## Introduction
-
The .NET Portability Analyzer helps you determine how flexible your application
is across .NET Platforms. For more information about platform portability
analysis, read ["Platform Portability"][PlatformPortability].
@@ -24,7 +22,6 @@ formats are:
* We only send .NET APIs to the service to analyze for portability. For more
information, our privacy policy is [here][PrivacyPolicy].
-
![Sample report][SampleReport]
## How to obtain