Принципы разрешения зависимостей пакетов в nuget

Интеграция 1С 8 и HostCMS

Интеграции 1С с сайтами очень сложно оценивать, ибо на сайте разработчика CMS, а может, и на странице конкретного модуля, зачастую можно найти инструкцию подключения обмена, но в ходе работы постоянно появляются подводные камни: то одно не выгружается, то другое, порой, кажется, все данные передаются, но документы или элементы справочников не заполняются. А перерабатывать типовой механизм зачастую бывает себе дороже. Причем бывают и ситуации, когда нужно вносить изменения и в 1С, и на сайте. Стоимость таких работ возрастает и встает вопрос о том, нужно ли это вообще. Сейчас я расскажу о том, как мы подключали HostCMS, а в конце статьи приведу результаты обмена.

Обновление пакета

1. в обозреватель решенийщелкните правой кнопкой мыши ссылки или нужный проект и выберите пункт управление пакетами NuGet…. (В проектах веб-сайтов щелкните правой кнопкой мыши папку bin .)

2. Перейдите на вкладку Обновления, чтобы просмотреть пакеты, для которых доступны обновления из выбранных источников пакетов. Выберите Включить предварительные версии, чтобы включить предварительные версии пакетов в список обновлений.

3. Последовательно выберите пакет для обновления и нужную версию в раскрывающемся списке справа, а затем щелкните Обновить.

4. Для некоторых пакетов отключена кнопка . При этом появляется сообщение «На этот пакет неявно ссылается пакет SDK» (AutoReferenced). Это сообщение означает, что пакет является частью более крупной платформы или пакета SDK и не должен обновляться отдельно. (Такие пакеты отмечаются атрибутом ). Например, является частью пакета SDK для .NET Core, и версия пакета не совпадает с версией платформы среды выполнения, используемой приложением. Необходимо обновить установку .NET Core, чтобы получить новые версии ASP.NET Core и среды выполнения .NET Core. См. подробнее о метапакетах и управлении версиями .NET Core. Это относится к следующим часто используемым пакетам:

   • Microsoft.AspNetCore.All
   • Microsoft.AspNetCore.App
   • Microsoft.NETCore.App
   • NETStandard.Library

5. Чтобы обновить несколько пакетов до их последних версий, выберите их в списке и нажмите кнопку Обновить над списком.

6. Кроме того, можно обновить отдельный пакет на вкладке установленные . В этом случае сведения о пакете включают в себя средство выбора версии (в соответствии с параметром включить предварительную версию) и кнопку обновления .

Visual Studio

установка на Visual Studio 2017 и более поздних версий

Начиная с версии Visual Studio 2017, установщик содержит диспетчер пакетов NuGet с любой рабочей нагрузкой, использующей .NET. чтобы установить отдельно или проверить, установлен ли диспетчер пакетов, запустите Visual Studio installer и установите флажок в разделе отдельные компоненты средства кода > NuGet диспетчер пакетов.

установка на Visual Studio 2015 и более старых версий

расширения NuGet для Visual Studio 2013 и 2015 можно загрузить из https://dist.nuget.org/index.html .

Для Visual Studio 2010 и более ранних версий установите расширение «Диспетчер пакетов NuGet для Visual Studio»

Обратите внимание, что если расширение не отображается на первой странице результатов поиска, попробуйте изменить раскрывающийся список сортировать на «большинство Скачиваний» или сортировку в алфавитном порядке

Что еще делает NuGet?

Мы уже выучили следующие характеристики NuGet:

• NuGet предоставляет центральный репозиторий nuget.org с поддержкой частного размещения.
• NuGet предоставляет разработчикам средства для создания, публикации и использования пакетов.
• Самое главное, NuGet ведет список ссылок для пакетов, используемых в проекте, а также позволяет восстанавливать и обновлять пакеты из этого списка.

Чтобы обеспечить эффективную работу этих процессов, NuGet осуществляет некоторые оптимизации в фоновом режиме. В частности, NuGet управляет кэшем пакета и папкой глобальных пакетов, что позволяет упростить установку и повторною установку. Кэш позволяет избежать загрузки пакета, который уже установлен на компьютере. Папка глобальных пакетов позволяет в нескольких проектах совместно использовать один установленный пакет, тем самым уменьшая общий размер пакетов NuGet на компьютере. Это очень удобно, когда вы часто восстанавливаете большее количество пакетов, например, как на сервере сборки. Дополнительные сведения об этих механизмах см. в статье Управление папкой установки глобальных пакетов, кэшем и временными папками.

В рамках отдельного проекта NuGet управляет общей схемой зависимостей, что включает в себя разрешение нескольких ссылок на различные версии одного пакета. Довольно часто проект зависит от одного или нескольких пакетов, имеющих такие же зависимости. Некоторые из наиболее полезных пакетов служебных программ на сайте nuget.org используются многими другими пакетами. В общей схеме зависимостей вы легко можете иметь десять различных ссылок на разные версии одного пакета. Чтобы избежать переноса нескольких версий этого пакета в само приложение, NuGet определяет, какую отдельную версию могут использовать все потребители. (Дополнительные сведения см. в разделе Принципы разрешения зависимостей пакетов в NuGet.)

кроме того, NuGet поддерживает все спецификации, связанные с структурированием пакетов (включая символы локализации и отладки) и способы их ссылки (включая и предварительные версии). NuGet также имеет различные API для работы со своими службами программно и предоставляет поддержку разработчикам, которые пишут расширения Visual Studio и шаблоны проектов.

Если изучить содержание этой документации, можно найти все указанные возможности и заметки о выпуске, отсылающие к самому начальному этапу развития NuGet.

Совместимость пакета с разными целевыми платформами

«Совместимый» пакет означает, что он содержит сборки, созданные по меньшей мере для одной целевой платформы .NET, совместимой с целевой платформой используемого проекта. Разработчики могут создавать пакеты, которые относятся к одной платформе, как и элементы управления универсальной платформы Windows (UWP), или они могут поддерживать более широкий набор целевых объектов. Для максимальной совместимости пакета разработчики используют версию .NET Standard, которую поддерживают все проекты .NET и .NET Core. Это наиболее эффективное средство как для создателей, так и для потребителей, так как единый пакет (обычно содержащий единую сборку) подходит для всех потребляющих проектов.

Разработчики пакетов, которым требуется API вне .NET Standard, с другой стороны, создают отдельные сборки для различных требуемых версий .NET Framework, которые они будут поддерживать, и включают все эти сборки в один пакет (который называется пакетом многоплатформенного нацеливания). Когда потребитель устанавливает такой пакет, NuGet извлекает только сборки, нужные в проекте. Это сводит к минимуму занимаемое пакетом место в конечном приложении или сборках, создаваемых данным проектом. Пакет настройки для различных версий, конечно, сложнее в обслуживании.

Примечание

Применение .NET Standard отменяет предыдущий подход использования различных целей переносной библиотеки классов (PCL). Таким образом, эта документация посвящена созданию пакетов для .NET Standard.

Configuring Newtonsoft in ASP.NET Core

When you’re using Newtonsoft directly, to customize serialization you have to pass in a JsonSerializerSettings object. When you’re using it with ASP.NET Core, you pass the JsonSerializerSettings object to a framework method. Internally, it’ll pass that settings object to Newtonsoft when it’s serializing / deserializing.

You can configure Newtonsoft at the service level and at the action level.

Service-level configuration

To configure Newtonsoft at the service level, use AddNewtonsoftJson() in Startup.ConfigureServices() like this:

In this example, it’s adding the StringEnumConverter. This makes Newtonsoft serialize / deserialize enums names instead of values.

This configuration applies to all controllers. When the framework needs to serialize a response object or deserialize a request with JSON, it’ll use the settings you provided.

Note: Newtonsoft deserializes enum values and names by default, but only serializes enum values by default. To make it serialize enum names, you have to make it use StringEnumConverter.

Action-level configuration

You can configure Newtonsoft at the action level for serialization (but not for deserialization). You can either pass back a JsonResult or directly call JsonConvert.SerializerObject().

I’d only recommend this approach as a last resort. If you need to customize serialization for the model type the controller is dealing with, you may want to consider creating a custom converter instead (and doing service-level configuration).

Option 1 – Return JsonResult

When you return a JsonResult object, the framework will serialize the model object using the serializer settings you passed in. It will use the current serializer (System.Text.Json or Newtonsoft).

Here’s an example:

Notice that the settings parameter is of type object. This isn’t type safe, and can lead to a runtime exception. For example, if you have Newtonsoft configured, and you pass in a System.Text.Json.JsonSerializerOptions object, you’ll get this runtime exception:

This means you have to know which serializer you’re using, which means it’s actually safer to directly call JsonConvert.SerializeObject().

Option 2 – Directly call JsonConvert.SerializeObject()

You always have the option of directly using Newtonsoft in the controller methods.

Here’s an example:

Note: If you use this approach, be sure to explicitly set the ContentType to application/json. This makes this option quite tedious.

Отслеживание ссылок и восстановление пакетов

Так как проекты можно легко перемещать между компьютерами разработчиков, репозиториями управления исходным кодом, серверами сборки и т. д., крайне непрактично хранить двоичные сборки из пакетов NuGet напрямую привязанными к проекту. В этом случае каждая копия проекта будет излишне раздутой (и, следовательно, расходовать пространство в репозиториях системы управления исходным кодом). Кроме того, обновить двоичные файлы пакета до новой версии будет очень сложно, так как обновление будет применяться ко всем копиям проекта.

Вместо этого NuGet поддерживает простой список ссылок на пакеты, от которых зависит проект, включая зависимости верхнего и нижнего уровня. То есть при установке пакета с некоторого узла в проект NuGet записывает идентификатор пакета и номер версии в этот список ссылок. (При удалении пакет, конечно же, убирается из этого списка.) Затем в NuGet можно восстановить все связанные пакеты по запросу, как описано в статье о восстановлении пакета.

используя только список ссылок, NuGet можете переустановить, то есть восстановить— все эти пакеты из общедоступных и (или) частных узлов в любое другое время. При фиксации проекта в системе управления исходным кодом или предоставления его для общего доступа каким-либо иным образом нужно включить только список ссылок и исключить какие-либо двоичные файлы пакета (см. раздел Пропуск пакетов NuGet в системах управления исходным кодом.)

Компьютер, принимающий проект, например сервер сборки, получающий копию проекта в рамках работы системы автоматического развертывания, просто запрашивает у NuGet восстановление зависимости всякий раз, когда они понадобятся. Системы сборки, такие как Azure DevOps, предоставляют шаги «Восстановление NuGet» именно для этой цели. Аналогично, когда разработчики получают копию проекта (например, при клонировании репозитория), они могут вызвать такие команды, как (CLI NuGet), (CLI dotnet) или (консоль диспетчера пакетов), чтобы получить все необходимые пакеты. Visual Studio, со своей стороны, автоматически восстанавливает пакеты при создании проекта (при условии, что включено автоматическое восстановление, как описано в статье Восстановление пакетов).

Очевидно, что основная роль NuGet, связанная с разработчиками, заключается в обслуживании этого списка ссылок от имени проекта и предоставлении средств для эффективного восстановления (и обновления) таких указанных в ссылках пакетов. Этот список хранится в одном из двух указанных ниже форматов управления пакетами:

• PackageReference (также известном как «Ссылки на пакет в файлах проекта»): (NuGet 4.0 и более поздних версий) ведет список зависимостей верхнего уровня проекта непосредственно в файле проекта, поэтому отдельный файл не требуется. Связанный файл создается динамически. Этот файл позволяет управлять общей схемой зависимостей пакетов, которые проект использует со всеми зависимостями нижнего уровня. В проектах .NET Core всегда используется формат PackageReference.

• : XML-файл, содержащий неструктурированный список всех зависимостей в проекте, включая зависимости других установленных пакетов. Установленные или восстановленные пакеты хранятся в папке .

Применение конкретного формата управления пакетами зависит от типа проекта и доступной версии Visual Studio и NuGet. Чтобы проверить, какой формат используется, просто найдите в корневом каталоге проекта после установки первого пакета. Если этот файл отсутствует, найдите в файле проекта элемент <PackageReference>.

При наличии возможности выбора рекомендуем использовать PackageReference. Файл используется в устаревших версиях и больше не применяется в активной разработке.

Совет

Различные команды интерфейса командной строки , например , не добавляют автоматически пакет в список ссылок. Этот список обновляется при установке пакета с помощью диспетчера пакетов Visual Studio (пользовательского интерфейса или консоли) и интерфейса командной строки .

Поиск и установка пакета

Для поиска и установки пакета необходимо выполнить три простых шага:

1. откройте проект или решение в Visual Studio и откройте консоль с помощью команды сервис NuGet диспетчер пакетов > диспетчер пакетов консоли .

2. Найдите пакет, который требуется установить. Если вы уже знакомы с этим процессом, перейдите к шагу 3.

3. Выполните команду установки:

Важно!

Все операции, доступные в консоли, также можно выполнить с помощью CLI NuGet. Но команды консоли работают в контексте Visual Studio и сохраненного проекта или решения, и область их применения часто шире, чем у их эквивалентов в CLI. Например, при установке пакета с помощью консоли добавляется ссылка на проект, а при использовании команды CLI этого не происходит. По этой причине разработчики, работающие в Visual Studio, обычно предпочитают использовать консоль вместо CLI.

Совет

Многие операции консоли зависят от наличия решения, открытого в Visual Studio с использованием известного имени пути. Если у вас нет решения или оно не сохранено, отобразится сообщение об ошибке «Решение не открыто или не сохранено. Убедитесь, что у вас есть открытое и сохраненное решение «. Это означает, что консоль не может определить папку решения. Эту ошибку можно исправить, сохранив несохраненное решение или создав и сохранив решение, если оно не открыто.

Основные сведения о версиях

Номер определенной версии выглядит следующим образом: Основной номер.Дополнительный номер.Исправление . Компоненты номера имеют следующие значения:

• Основной номер: Критические изменения
• Дополнительный номер: новые функции; сохраняется обратная совместимость;
• Исправление: исправления ошибок; сохраняется обратная совместимость.
• -Суффикс (необязательно): дефис, за которым следует строка, обозначающая предварительную версию (в соответствии с Семантическим версионированием (или соглашением SemVer 1.0)).

Примеры

Важно!

nuget.org отклоняет любую загрузку пакета, в которой отсутствует точный номер версии. Версия должна быть указана в или файле проекта, с помощью которого был создан пакет.

Предварительные версии

С технической точки зрения, создатели пакетов могут использовать любую строку в качестве суффикса для обозначения предварительной версии, так как NuGet рассматривает любую такую версию как предварительную версию, не делая других интерпретаций. Это значит, что NuGet отображает полную строку версии в любом пользовательском интерфейсе, предоставляя потребителю возможность по-своему интерпретировать значение суффикса.

Тем не менее, разработчики пакетов обычно следуют общепризнанным соглашениям об именовании:

• . альфа-версия, обычно используемая для текущей работы и экспериментирования;
• . бета-версия, которая обычно содержит полный набор функций для следующего запланированного выпуска, но может иметь известные ошибки;
• . версия-кандидат, которая обычно может служить итоговой (стабильной), если не будут выявлены серьезные ошибки.

Примечание

NuGet 4.3.0+ поддерживает соглашение SemVer 2.0.0, которое позволяет использовать номера предварительных версий с точечной нотацией, как в случае с 1.0.1-build.23. В версиях NuGet, предшествующих 4.3.0, точечная нотация не поддерживается. Вы можете использовать такую форму, как 1.0.1-build23.

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

Средства CLI

для поддержки функций NuGet в интегрированной среде разработки можно использовать интерфейс командной строки или cli. Средство CLI устанавливается вместе с некоторыми рабочими нагрузками Visual Studio, например .NET Core. Средство CLI нужно установить отдельно, как описано выше.

Два средства CLI для NuGet — и . См. сравнительную таблицу .

• Для нацеливания на .NET Core или .NET Standard используйте CLI для .NET. CLI является обязательным для проекта на основе пакета SDK, использующего .
• Для нацеливания на .NET Framework (только проекты не на основе пакетов SDK) используйте CLI . Если проект переносится из в PackageReference, используйте CLI dotnet.

Интерфейс командной строки dotnet.exe

Интерфейс командной строки .NET Core 2.0, , работает на всех платформах (Windows, Mac и Linux) и предоставляет такие возможности NuGet, как установка, восстановление и публикация пакетов. обеспечивает прямую интеграцию с файлами проекта .NET Core (например, ), что полезно в большинстве сценариев. также создается непосредственно для каждой платформы и не требует установки Mono.

Установка:

• на компьютерах разработчиков установите пакет SDK для .NET Core; Начиная с версии Visual Studio 2017, средство CLI dotnet автоматически устанавливается вместе с любыми рабочими нагрузками, связанными с .NET Core.
• для серверов сборки следуйте инструкциям в статье Использование пакета SDK и средств .NET Core при непрерывной интеграции (CI).

Сведения об использовании основных команд с CLI dotnet см. в статье Установка и использование пакета с помощью CLI dotnet.

Интерфейс командной строки nuget.exe

Интерфейс командной строки () — это программа командной строки для Windows, которая предоставляет все возможности NuGet. С некоторыми ограничениями ее также можно запустить на Mac OSX и Linux с помощью .

Сведения об использовании основных команд с CLI см. в статье .

Установка:

Windows

Примечание

Для выполнения NuGet.exe 5.0 и более поздних версий требуется .NET Framework 4.7.2 или более поздней версии.

1. Перейдите к странице nuget.org/downloads и выберите NuGet 3.3 или более поздней версии (версия 2.8.6 не совместима с Mono). Рекомендуем всегда использовать последнюю версию. Кроме того, для публикации пакетов на nuget.org требуется версия 4.1.0 и выше.
2. Для каждой версии непосредственно скачивается файл . Укажите браузеру сохранять файл в выбранную вами папку. Этот файл не является установщиком. Если запустить его непосредственно из браузера, ничего не отображается.
3. Добавьте папку с в переменную среды PATH, чтобы использовать средство CLI из любого расположения.

Mac OS и Linux

Поведение для этих ОС может несколько различаться.

1. Установите Mono 4.4.2 или более поздней версии.

2. В командной строке оболочки введите следующие команды:

3. Создайте псевдоним, добавив следующий скрипт к соответствующему файлу для вашей операционной системы (обычно или ):

4. Перезагрузите оболочку. Проверьте установку. Для этого введите без параметров. Должно отобразиться окно справки NuGet CLI.

Совет

Вы можете обновить существующий nuget.exe до последней версии с помощью команды в Windows.

Примечание

Последняя рекомендуемая версия интерфейса командной строки NuGet всегда доступна по адресу . В целях совместимости с более старыми системами непрерывной интеграции, предыдущий URL-адрес в настоящее время предоставляет .

Когда следует переустанавливать пакет

1. Нарушенные ссылки после восстановления пакета: если вы открыли проект и восстановили пакеты NuGet, но по-прежнему видите нарушенные ссылки, попробуйте переустановить каждый из этих пакетов.
2. Проект нарушен из-за удаленных файлов: NuGet не запрещает вам удалять элементы, добавленные из пакетов, поэтому вы легко можете случайно изменить содержимое, установленное из пакета, и нарушить работу проекта. Чтобы восстановить проект, переустановите затронутые пакеты.
3. Обновление пакета нарушило работу проекта. Если обновление пакета нарушает работу проекта, причиной сбоя обычно является пакет зависимостей, который также мог быть обновлен. Чтобы восстановить состояние зависимости, переустановите этот пакет.
4. Перенацеливание или обновление проекта: это может быть полезно, когда проект был перенацелен или обновлен и если он требует переустановки из-за изменения целевой платформы. В таких случаях NuGet выдает ошибку сборки сразу после перенацеливания проекта, а последующие предупреждения сборки сообщают, что для пакета может потребоваться переустановка. Для обновления проекта NuGet выводит ошибку в журнале обновления проекта.
5. Переустановка пакета во время его разработки: авторам пакетов часто требуется переустановить ту версию пакета, которую они разрабатывают, для тестирования поведения. Команда не предоставляет возможность принудительной переустановки, поэтому используйте вместо нее .

Доступность консоли

начиная с Visual Studio 2017 NuGet и диспетчер пакетов NuGet устанавливаются автоматически при выборе любого из них. Рабочие нагрузки, связанные с NET; его также можно установить по отдельности, установив флажки средства кода отдельных компонентов > NuGet диспетчер пакетов в установщике Visual Studio.

кроме того, если в Visual Studio 2015 и более ранних версий отсутствует диспетчер пакетов NuGet, проверьте расширения и обновления инструментов и найдите расширение NuGet диспетчер пакетов. Если вы не можете использовать установщик расширений в Visual Studio, скачайте расширение отсюда: https://dist.nuget.org/index.html.

Консоль диспетчера пакетов сейчас недоступна в Visual Studio для Mac. Но аналогичные команды доступны через CLI NuGet. В Visual Studio для Mac есть пользовательский интерфейс для управления пакетами NuGet. См. подробнее о включении пакета NuGet в проект.

Консоль диспетчера пакетов не входит в Visual Studio Code.

Средства NuGet

Кроме поддержки размещения, NuGet также предоставляет широкий набор средств, используемых как создателями, так и потребителями. Сведения о получении конкретных средств см. в разделе Установка клиентских средств NuGet.

Как видите, средства NuGet, с которыми вы работаете, в значительной степени зависят от того, создаете, потребляете или публикуете вы пакеты, а также от используемой платформы. Создатели пакета обычно также являются потребителями, так как берут за основу функции, имеющиеся в других пакетах NuGet. Конечно же, те пакеты, в свою очередь, могут зависеть еще от каких-либо.

Дополнительные сведения см. в статье Рабочий процесс создания пакета и Рабочий процесс использования пакета.