Бывало ли у Вас такое, что обновили библиотеку на minor/patch версию и всё успешно скомпилировалось, но запускаете проект и получаете ошибку в рантайме случайным образом?
Например TypeNotFoundException или MissingMethodException, MissingMemberException и т.п.
Или когда обновили казалось бы на мажорную версию, но при этом всё прекрасно работает.
В первом случае, вероятнее всего, Вы столкнулись с пакетом в котором не особо следят за зависимостями или совместимостью публичного API.
Во втором случае, вероятно Вы не используете функции, совместимость которых была сломана и из-за которых пришлось поднять мажорную версию.
Либо же мажорная версия была присвоена "за компанию", когда разработчик версионирует пакеты вместе и выпускает их все, даже если что-то поменялось в одном. Это достаточно удобно и широко распространенная практика.
Есть несколько видов совместимостей API:
- Совместимость поведения - это то, как ведут себя функции в библиотеке. Сохранять совместимость можно зафиксировав поведение обычными тестами.
- Совместимость исходного кода - возможность использовать новую версию библиотеки и скомпилировать без изменения кода
- Бинарная совместимость - возможность использовать новую версию библиотеки даже без перекомпиляции
- есть и другие
За редким исключением, почти все библиотеки в .NET поставляются уже скомпилированными (dll) и используется таковыми.
Поэтому самая коварная здесь - совместимость бинарная. Её легче всего пропустить и надо знать много нюансов.
А всё потому что, казалось бы, внесли незначительное изменение - например добавили необязательный параметр в метод, но бинарная совместимость уже нарушена.
В рантайме будет ошибка т.к. с его точки зрения это новый метод, а старый удалили.
Именно поэтому в BCL можно встретить массу API, где ради бинарной совместимости добавляются новые перегрузки, вместо добавления необязательного параметра в существующие методы.
О том, какие изменения потенциальные breaking changes, можно почитать здесь.
И так, разобрались с совместимостью API, теперь поговорим о такой штуке как "транзитивные зависимости".
Простейший пример - есть пакет (1), который зависит от другого пакета (2). При этом Ваш проект не подключал пакет (2) явно, оно "пришло" вместе с пакетом (1), так как ему она нужна для работы.
Вполне возможно что есть и пакет (3), который тоже зависит от пакета (2), но другой версии.
Хорошо если они отличаются на патч или минорную версию и разработчик пакета (2) следит за совместимостью API библиотеки. Тогда никаких проблем быть не должно.
Но может быть хуже - когда пакеты (1) и (3) ожидают совершенно разные версии и между этими версиями есть breaking changes. Ошибки будут в рантайме.
В .NET каждая библиотека в итоговую сборку попадает лишь один раз. Если к примеру подключены версии 1.0.0 и 1.1.0 - то в итоге будет выбран 1.1.0. Предпочтение всегда идет более свежей версии.
Если к запускаемой сборке явно подключить версию 2.0.0, то в итоговую сборку попадет именно она.
При этом библиотеки будут думать что работают с версией 1.0.0 и 1.1.0, но в реальности будут работать с 2.0.0.
А ведь зависимостей много! И чтобы руками всё не проверять, можно сбилдить любой проект и зайти в bin/Debug/{framework version}/{project name}.deps.json
В этом файле собраны все зависимости проекта и всех пакетов в нем, причем уже с разрешенными версиями.
Если у Вас возник вопрос можно ли обновить такой-то пакет на свежую версию, то лучше всего проверить совместимость с текущей специальными утилитами, например apicompat:
dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool
сравниваем совместимость пакетов с текущей (baseline) и новой версией:
apicompat package "C:\path\to\package.1.0.0.nupkg" --baseline-package "C:\path\to\package.1.1.0.nupkg"
в ответ должны получить APICompat выполнен без обнаружения критических изменений. или же набор отличий между версиями, если они обнаружены.
Если вы разрабатываете библиотеку, то рекомендую подключить анализатор, чтобы контролировать публичные API ваших библиотек и строго придерживаться semver и тогда потребители ваших библиотек будут счастливы :)
Например TypeNotFoundException или MissingMethodException, MissingMemberException и т.п.
Или когда обновили казалось бы на мажорную версию, но при этом всё прекрасно работает.
В первом случае, вероятнее всего, Вы столкнулись с пакетом в котором не особо следят за зависимостями или совместимостью публичного API.
Во втором случае, вероятно Вы не используете функции, совместимость которых была сломана и из-за которых пришлось поднять мажорную версию.
Либо же мажорная версия была присвоена "за компанию", когда разработчик версионирует пакеты вместе и выпускает их все, даже если что-то поменялось в одном. Это достаточно удобно и широко распространенная практика.
Есть несколько видов совместимостей API:
- Совместимость поведения - это то, как ведут себя функции в библиотеке. Сохранять совместимость можно зафиксировав поведение обычными тестами.
- Совместимость исходного кода - возможность использовать новую версию библиотеки и скомпилировать без изменения кода
- Бинарная совместимость - возможность использовать новую версию библиотеки даже без перекомпиляции
- есть и другие
За редким исключением, почти все библиотеки в .NET поставляются уже скомпилированными (dll) и используется таковыми.
Поэтому самая коварная здесь - совместимость бинарная. Её легче всего пропустить и надо знать много нюансов.
А всё потому что, казалось бы, внесли незначительное изменение - например добавили необязательный параметр в метод, но бинарная совместимость уже нарушена.
В рантайме будет ошибка т.к. с его точки зрения это новый метод, а старый удалили.
Именно поэтому в BCL можно встретить массу API, где ради бинарной совместимости добавляются новые перегрузки, вместо добавления необязательного параметра в существующие методы.
О том, какие изменения потенциальные breaking changes, можно почитать здесь.
И так, разобрались с совместимостью API, теперь поговорим о такой штуке как "транзитивные зависимости".
Простейший пример - есть пакет (1), который зависит от другого пакета (2). При этом Ваш проект не подключал пакет (2) явно, оно "пришло" вместе с пакетом (1), так как ему она нужна для работы.
Вполне возможно что есть и пакет (3), который тоже зависит от пакета (2), но другой версии.
Хорошо если они отличаются на патч или минорную версию и разработчик пакета (2) следит за совместимостью API библиотеки. Тогда никаких проблем быть не должно.
Но может быть хуже - когда пакеты (1) и (3) ожидают совершенно разные версии и между этими версиями есть breaking changes. Ошибки будут в рантайме.
В .NET каждая библиотека в итоговую сборку попадает лишь один раз. Если к примеру подключены версии 1.0.0 и 1.1.0 - то в итоге будет выбран 1.1.0. Предпочтение всегда идет более свежей версии.
Если к запускаемой сборке явно подключить версию 2.0.0, то в итоговую сборку попадет именно она.
При этом библиотеки будут думать что работают с версией 1.0.0 и 1.1.0, но в реальности будут работать с 2.0.0.
А ведь зависимостей много! И чтобы руками всё не проверять, можно сбилдить любой проект и зайти в bin/Debug/{framework version}/{project name}.deps.json
В этом файле собраны все зависимости проекта и всех пакетов в нем, причем уже с разрешенными версиями.
Если у Вас возник вопрос можно ли обновить такой-то пакет на свежую версию, то лучше всего проверить совместимость с текущей специальными утилитами, например apicompat:
dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool
сравниваем совместимость пакетов с текущей (baseline) и новой версией:
apicompat package "C:\path\to\package.1.0.0.nupkg" --baseline-package "C:\path\to\package.1.1.0.nupkg"
в ответ должны получить APICompat выполнен без обнаружения критических изменений. или же набор отличий между версиями, если они обнаружены.
Если вы разрабатываете библиотеку, то рекомендую подключить анализатор, чтобы контролировать публичные API ваших библиотек и строго придерживаться semver и тогда потребители ваших библиотек будут счастливы :)