Используйте Microsoft.CodeAnalysis.PublicApiAnalyzers для контроля публичного API ваших библиотек
При разработке библиотек бывает сложно определить что будет считаться breaking change, а что нет и можно случайно что-нибудь сломать потребителям, что может породить лишнюю работу и недовольства.
Вышеупомянутая библиотека является Roslyn анализатором и после подключения он будет требовать, чтобы все публичные типы и члены были зафиксированы в файлах PublicAPI.Shipped.txt и PublicAPI.Unshipped.txt.
Если что-то не было в нем зафиксировано, он выдаст ошибку RS0016:
DomainException.cs(124,28): Error RS0016 : Символ "Check" не является частью объявленного общедоступного API.
Удобно то, что можно быстро перейти к этому символу и через alt + enter добавить в Unshipped.
А чтобы вручную не заполнять, можно просто ввести команду ниже и потом перенести из Unshipped в Shipped то что уже в релизе.
dotnet format analyzers --diagnostics=RS0016
Если удалить публичный метод или тип, поменять значение по-умолчанию в аргументе метода, добавить аргумент с дефолтным значением в уже существующий метод и прочее, то будет выведена ошибка такого типа:
PublicAPI.Shipped.txt(37,1): Error RS0017 : Символ "Sstv.DomainExceptions.DomainException.WithDetailedMessage(string? detailedMessage) -> Sstv.DomainExceptions.DomainException!" является частью объявленного API, однако не является открытым либо не был найден
Данный подход поможет снизить объем случайных ломающих изменений при очередном релизе библиотеки.
Однако он требует определенного уровня терпения.
В период активной разработки может мешать и приходится выключать через .editorconfig или NoWarn в csproj.
Также есть альтернативный подход, основанный на тестах.
Можно с помощью snapshot тестов сохранять весь публичный API в файл и таким образом проверять что ничего не изменилось.
С одной стороны здесь пишем один раз тест и больше не нужно вручную обновлять PublicAPI.Shipped.txt, с другой надо постоянно запускать эти тесты. А это дает несколько более долгий цикл обратной связи для разработчика, нежели вариант с анализатором.
И для наглядности - пример использования библиотеки:
базовый и продвинутый, когда требуется писать библиотеку с поддержкой нескольких TargetFramework и хочется настроить подключение в одном месте для всех NuGet пакетов.
При разработке библиотек бывает сложно определить что будет считаться breaking change, а что нет и можно случайно что-нибудь сломать потребителям, что может породить лишнюю работу и недовольства.
Вышеупомянутая библиотека является Roslyn анализатором и после подключения он будет требовать, чтобы все публичные типы и члены были зафиксированы в файлах PublicAPI.Shipped.txt и PublicAPI.Unshipped.txt.
Если что-то не было в нем зафиксировано, он выдаст ошибку RS0016:
DomainException.cs(124,28): Error RS0016 : Символ "Check" не является частью объявленного общедоступного API.
Удобно то, что можно быстро перейти к этому символу и через alt + enter добавить в Unshipped.
А чтобы вручную не заполнять, можно просто ввести команду ниже и потом перенести из Unshipped в Shipped то что уже в релизе.
dotnet format analyzers --diagnostics=RS0016
Если удалить публичный метод или тип, поменять значение по-умолчанию в аргументе метода, добавить аргумент с дефолтным значением в уже существующий метод и прочее, то будет выведена ошибка такого типа:
PublicAPI.Shipped.txt(37,1): Error RS0017 : Символ "Sstv.DomainExceptions.DomainException.WithDetailedMessage(string? detailedMessage) -> Sstv.DomainExceptions.DomainException!" является частью объявленного API, однако не является открытым либо не был найден
Данный подход поможет снизить объем случайных ломающих изменений при очередном релизе библиотеки.
Однако он требует определенного уровня терпения.
В период активной разработки может мешать и приходится выключать через .editorconfig или NoWarn в csproj.
Также есть альтернативный подход, основанный на тестах.
Можно с помощью snapshot тестов сохранять весь публичный API в файл и таким образом проверять что ничего не изменилось.
С одной стороны здесь пишем один раз тест и больше не нужно вручную обновлять PublicAPI.Shipped.txt, с другой надо постоянно запускать эти тесты. А это дает несколько более долгий цикл обратной связи для разработчика, нежели вариант с анализатором.
И для наглядности - пример использования библиотеки:
базовый и продвинутый, когда требуется писать библиотеку с поддержкой нескольких TargetFramework и хочется настроить подключение в одном месте для всех NuGet пакетов.