Анализатор переносимости .NET

Примечание.

Порт API устарел в пользу двоичного анализа помощником по обновлению .NET. Серверная служба порта API завершена, поэтому для использования средства необходимо использовать его в автономном режиме. Дополнительные сведения см. в статье .NET API Port README.

Хотите, чтобы ваши библиотеки поддерживали несколько платформ? Хотите узнать, какой объем работ требуется проделать, чтобы ваше приложение .NET Framework работало в .NET Core? Анализатор переносимости .NET — это средство, которое анализирует сборки и предоставляет подробный отчет об отсутствующих API-интерфейсах .NET для приложений или библиотек, которые переносятся на заданные целевые платформы .NET. Анализатор переносимости предоставляется в виде расширения Visual Studio, который анализирует одну сборку для каждого проекта, а также как консольное приложение ApiPort, которое анализирует сборки по указанным файлам или каталогу.

После преобразования проекта на новую платформу, например .NET Core, вы можете использовать анализатор совместимости платформы на основе Roslyn для выявления ИНТЕРФЕЙСов API, которые вызывают PlatformNotSupportedException исключения и другие проблемы совместимости.

Стандартные целевые платформы

• .NET Core: имеет модульную структуру, поддерживает параллельное установку и предназначение кроссплатформенных сценариев. Параллельная установка позволяет внедрять новые версии .NET Core, не влияя на работоспособность других приложений. Если ваша цель — перенос веб-приложения в .NET Core для обеспечения поддержки нескольких платформ, это рекомендуемый целевой объект.
• .NET Standard: включает API .NET Standard, доступные во всех реализациях .NET. Если ваша цель — выполнение библиотеки на всех поддерживаемых платформах .NET, это рекомендуемый целевой объект.
• ASP.NET Core: современная веб-платформа, основанная на .NET Core. Если вашей целью является перенос веб-приложения на .NET Core для поддержки нескольких платформ, это рекомендуемый целевой объект.
• Расширения платформы .NET Core и платформы: включает API .NET Core в дополнение к пакету совместимости Windows, который предоставляет множество доступных технологий платформа .NET Framework. Это рекомендуемый целевой объект для переноса приложения из .NET Framework на .NET Core в Windows.
• Расширения платформы .NET Standard и платформы: включает api .NET Standard в дополнение к пакету совместимости Windows, который предоставляет множество доступных технологий платформа .NET Framework. Это рекомендуемый целевой объект для переноса библиотеки из .NET Framework на .NET Core в Windows.

Как использовать анализатор переносимости .NET

Чтобы начать пользоваться анализатором переносимости .NET в Visual Studio, скачайте и установите расширение из Visual Studio Marketplace. Он работает на версиях Visual Studio 2017 и Visual Studio 2019.

Внимание

Анализатор переносимости .NET не поддерживается в Visual Studio 2022.

Настройте его в Visual Studio, выбрав Анализ>Параметры анализатора переносимости и указав целевые платформы, являющиеся платформами или версиями .NET, для которых вы хотите оценить пропуски в переносимости по сравнению с платформой или версией, на которой собрана ваша текущая сборка.

Можно также использовать консольное приложение ApiPort, загрузив его из репозитория ApiPort. Можно использовать параметр команды listTargets, чтобы отобразить список доступных целевых платформ, а затем выбрать целевые платформы, указав параметр команды -t или --target.

Представление, охватывающее все решение

Полезным шагом при анализе решения с множеством проектов стала бы визуализация зависимостей, позволяющая понять, от чего именно зависит каждое такое подмножество сборок. Общая рекомендация заключается в применении результатов анализа по принципу "снизу вверх", начиная с листовых узлов в графе зависимостей.

Чтобы получить эти сведения, можно выполнить следующую команду.

ApiPort.exe analyze -r DGML -f [directory or file]

При открытии в Visual Studio результат будет выглядеть следующим образом.

Анализ переносимости

Чтобы проанализировать весь проект в Visual Studio, щелкните его правой кнопкой мыши в обозревателе решений и выберите пункт Анализировать переносимость сборки. Или в меню Анализ выберите Анализировать переносимость сборки. После этого выберите исполняемый файл или DLL-файл проекта.

Можно также использовать консольное приложение ApiPort.

Введите следующую команду для анализа текущего каталога:

ApiPort.exe analyze -f .

Чтобы проанализировать определенный список файлов .dll, введите следующую команду:

ApiPort.exe analyze -f first.dll -f second.dll -f third.dll

Чтобы выбрать определенную версию, используйте -t параметр:

ApiPort.exe analyze -t ".NET, Version=5.0" -f .

Запустите ApiPort.exe -? , чтобы получить дополнительную помощь.

Рекомендуется включать все связанные файлы EXE и DLL, которые у вас есть и которые вы хотите перенести, а также исключить файлы, от которых зависит приложение, но у вас их нет и вы не хотите их переносить. Это позволит получить наиболее актуальный отчет о переносимости.

Просмотр и интерпретация результатов переносимости

В отчете отображаются только интерфейсы API, которые не поддерживаются целевой платформой. После выполнения анализа в Visual Studio вы увидите ссылку на файл отчета о переносимости .NET. Если вы использовали консольное приложение ApiPort, ваш отчет о переносимости .NET сохраняется как файл в формате, который вы указали. По умолчанию используется файл Excel (.xlsx) в текущем каталоге.

Сводка переносимости

В разделе со сводкой по переносимости в этом отчете показан процент переносимости для каждой сборки, включенной в анализ. В предыдущем примере 71,24 % API-интерфейсов .NET Framework, используемых в приложении svcutil, доступны в .NET Core и расширениях платформы. Если запустить анализатор переносимости .NET для нескольких сборок, каждая сборка должна иметь строку в сводном отчете о переносимости.

Сведения

В разделе Details (Подробные сведения) в отчете указываются API, отсутствующие на любой из выбранных целевых платформ.

• Тип целевого объекта: в типе есть API, отсутствующие на целевой платформе.
• Член целевого объекта: метод отсутствует на целевой платформе.
• Имя сборки: сборка .NET Framework, в которой находится отсутствующий API.
• Каждая из выбранных целевых платформ является одним столбцом, например .NET Core": "Не поддерживается" означает, что API не поддерживается на этой целевой платформе.
• Рекомендованные изменения: рекомендованный API или технология для замены. В настоящее время это поле является пустым или устарело для многих интерфейсов API. Ввиду большого количества API нам сложно поддерживать актуальность. Мы рассматриваем альтернативные решения, чтобы предоставлять клиентам полезные сведения.

Отсутствующие сборки

В отчете есть раздел "Отсутствующие сборки". В данном разделе приводится список сборок, на которые ссылаются проанализированные сборки и которые не были проанализированы. Если эта сборка принадлежит вам, включите ее в анализ переносимости API, чтобы получить по ней подробный отчет о переносимости на уровне API. Если это библиотека стороннего производителя, проверьте наличие актуальной версии, поддерживающей целевую платформу, и рассмотрите возможность перехода на более новую версию. В конечном счете список должен включать все сторонние сборки, от которых зависит ваше приложение, и вы должны проверить, что у них есть версии, которые поддерживают вашу целевую платформу.

Дополнительные сведения об анализаторе переносимости .NET см. в документации по GitHub.