Приватный NuGet-сервер Быстрые отчеты

В статье про работу с NuGet-пакетами мы рассмотрели все особенности использования с программным обеспечением Быстрые отчеты. Один из самых частых вопросов наших клиентов:

Как нам установить ваши лицензионные пакеты в наш продукт, используя Linux, MacOS либо Windows. При этом нам бы не приходилось устанавливать последнюю версию продуктов FastReport вручную с помощью инсталлера, скачанного на сайте, который работает только на Windows?

На этот вопрос мы подготовили универсальное решение в виде нашего приватного NuGet-сервера Быстрые отчеты.

Что это и зачем?

Почти все пакеты, которые вы используете в своих проектах, находятся в общедоступном хранилище пакетов - NuGet Gallery (nuget.org). Там же вы можете найти разные демоверсии наших пакетов, однако, там нет наших пакетов без ограничений демоверсии. По этой причине мы приняли решение о создании собственного хранилища пакетов, доступным только для клиентов Быстрые отчеты. Соответственно, для доступа к нему у вас должен быть аккаунт Быстрые отчеты (с помощью этого аккаунта вы могли зайти на https://лк.быстрыеотчеты.рф/ для загрузки установщика продукта).

Добавление источника

Мы рассмотрим несколько вариантов добавления нашего NuGet-сервера:

• .NET CLI
• Visual Studio
• Visual Studio for Mac
• Rider
• nuget.exe CLI
• NuGet.Config
• Docker

Но сначала стоит рассказать о различиях глобального и локального конфига NuGet.

Глобальный и локальный NuGet.Config

Рассмотрим процесс восстановления пакетов, использующихся в вашем проекте:

1)    NuGet ищет необходимые пакеты в кэше

2)    NuGet ищет необходимые пакеты во всех источниках, добавленных в файл NuGet.Config, при этом:

a)    NuGet обращается к локальному NuGet.Config

b)    NuGet обращается к глобальному NuGet.Config

Локальный файл NuGet.Config располагается рядом с вашим проектом. Соответственно, добавленные туда источники будут использоваться только для восстановления данного проекта.

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

Расположение глобального конфига NuGet.Config:

Windows: "C:\Users\{имя_пользователя}\AppData\Roaming\NuGet\NuGet.Config"
MacOS: "~/.config/NuGet/NuGet.Config"
Linux: “~/.config/NuGet/NuGet.Config”

Соответственно, имя сервера, его адрес и ваши данные (email с паролем к этому серверу) по спецификации NuGet должны быть записаны в файл с названием NuGet.Config (либо nuget.config), который будет расположен в удобном для вас месте.

Хранение пароля в зашифрованном и незашифрованном виде

Файл конфигурации NuGet.Config умеет хранить пароль от источника как в зашифрованном виде, так и в формате ClearTextPassword. В большинстве случаев рекомендуется хранить пароль в зашифрованном виде, однако при этом, шифрование происходит с использованием параметров внешнего окружения (операционная система, конфигурация компьютера и т.д.). Следовательно, если перенести этот файл конфигурации на другую машину, указанный пароль не сможет дешифроваться и доступ к источнику вы не получите. Это необходимо учитывать при выборе способа добавления или обновления источника.

Далее мы рассмотрим основные способы добавления нашего источника в NuGet с указанием операционной системы совместимой с данным методом. А также не забудем о доступных типах конфигурации и о формате хранения пароля от источника.

.NET CLI:

(любая ОС, любой конфиг, любой вид хранения пароля)

Для работы данного способа необходимо иметь установленный SDK .NET Core 3.1.200 и выше (в том числе SDK .NET 5 и выше). Впишем в командной строке:

dotnet nuget add source https://nuget.быстрыеотчеты.рф/api/v3/index.json --name [выберете имя источника без пробелов, например: fr_nuget] --username [email вашего аккаунта Быстрые отчеты] --password [пароль от вашего аккаунта Быстрые отчеты]

По умолчанию эта команда добавляет источник в глобальный NuGet.Config, однако вы можете выбрать расположение файла конфигурации и сделать его локальным с помощью параметра --configfile [путь до файла конфигурации].

Ещё по умолчанию пароль от источника шифруется, а для хранения пароля в незашифрованном виде необходимо использовать параметр --store-password-in-clear-text.

Пример:

dotnet nuget add source https://nuget.быстрыеотчеты.рф/api/v3/index.json --name fr_nuget --username myaccount@fastreport.ru --password 1234Password5678

Подробнее об этом способе добавления источника вы можете прочитать на сайте Microsoft.

Microsoft Visual Studio:

(Windows, глобальный конфиг, зашифрованный пароль)

Рассмотрим добавление NuGet-сервера на примере Microsoft Visual Studio 2022. Важно учитывать, что данный способ работает начиная с Visual Studio 2017. В меню выбираем ‘Tools’, затем ‘NuGet Package Manager’ и открываем окно под названием ‘Package Manager Settings’.

Затем слева выбираем пункт ‘Package Sources’ и нажимаем на кнопку + (add).

Вписываем в поле ‘Name’ имя источника без пробелов (например, FastReport-NuGet), а в поле ‘Source’ вводим адрес источника: https://nuget.быстрыеотчеты.рф/api/v3/index.json

Нажимаем на кнопку ‘ОК’ и после этого переходим на окно добавления пакетов.

В выпадающем меню ‘Package source’ выбираем только что добавленный источник. Затем в диалоговом окне заполняем данные от аккаунта Быстрые отчеты и нажимаем на пункт “Запомнить мой пароль”.

Microsoft Visual Studio for Mac:

(macOS, глобальный конфиг, зашифрованный пароль)

Рассмотрим на примере Microsoft Visual Studio for Mac 2019.

В меню выбираем ‘Project’ и открываем окно ‘Manage NuGet Packages…’.

Внизу в выпадающем меню ‘Package source’ выбираем пункт ‘Configure Sources…’.

Нажимаем на кнопку Add и в окне заполняем данные:

- Name: имя источника без пробелов (например FastReport-Nuget);
- Location: https://nuget.быстрыеотчеты.рф/api/v3/index.json;
- Username: email от аккаунта Быстрые отчеты;
- Password: пароль от аккаунта Быстрые отчеты.

Подтверждаем добавление источника кнопкой ‘Add Source’.

JetBrains Rider:

(любая ОС, глобальный конфиг, зашифрованный пароль)

Рассмотрим на примере Rider 2021.3 на Linux Ubuntu 18.04.

Переходим в меню ‘Tools’, ‘NuGet’ и выбираем пункт ‘Show NuGet Sources’.

В окне NuGet в пункте ‘Sources’ напротив ‘New feed’ нажимаем на +.

Вносим необходимые данные:

- Name - имя источника без пробелов (например FastReport-Nuget);
- URL - https://nuget.быстрыеотчеты.рф/api/v3/index.json;
- User - email от аккаунта Быстрые отчеты;
- Password - пароль от аккаунта Быстрые отчеты.

Nuget.exe CLI:

(любая ОС (для macOS/Linux требуется Mono 4.4.2 или выше), любой конфиг, любой вид хранения пароля)

Установка nuget.exe подробно описана на сайте Microsoft. Мы сейчас рассмотрим лишь важные моменты.

nuget sources add -name [выберете имя источника без пробелов, например: fr_nuget] -source “https://nuget.быстрыеотчеты.рф/api/v3/index.json” -username [email вашего аккаунта Быстрые отчеты] -password [пароль от вашего аккаунта Быстрые отчеты]

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

Изначально пароль от источника шифруется, для хранения пароля в незашифрованном виде используйте параметр -StorePasswordInClearText

Пример:

nuget sources add -name fr_nuget -source “https://nuget.быстрыеотчеты.рф/api/v3/index.json” -username myaccount@fastreport.ru -password 1234Password5678

Подробнее об этом способе добавления источника вы можете прочитать на сайте Microsoft.

Edit NuGet.Config:

(любая ОС, любой конфиг, незашифрованный пароль)

Важно! Данным способом указать ваш пароль от аккаунта Быстрые отчеты можно только в незашифрованном виде. Так как файл конфигурации это обычный XML файл. Он открывается или создается любым текстовым редактором. В блоке ‘packageSources’ необходимо добавить наш ресурс с выбранным названием (использование пробелов нежелательно), например:

<add key="FR-NuGet" value="https://nuget.быстрыеотчеты.рф/api/v3/index.json" />

В блок ‘packageSourceCredentials’ необходимо добавить ваш email и пароль от аккаунта Быстрые отчеты в блок с идентичным key:

 <FR-NuGet>
 <add key="Username" value="myaccount@fastreport.ru" />
 <add key="ClearTextPassword" value="1234Password5678" />
 </FR-NuGet>

В итоге должен получиться похожий файл конфигурации (остальные источники убраны из примера):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
 <packageSources>
 <add key="FR-NuGet" value="https://nuget.быстрыеотчеты.рф/api/v3/index.json" />
 </packageSources>
 <packageSourceCredentials>
 <FR-NuGet>
 <add key="Username" value="myaccount@fastreport.ru" />
 <add key="ClearTextPassword" value="1234Password5678" />
 </FR-NuGet>
 </packageSourceCredentials>
</configuration>

Docker:

(любая ОС, любой конфиг, незашифрованный пароль)

В Dockerfile при создании docker-образа вы должны добавить источник используя либо .NET CLI, либо переместить заранее подготовленный файл конфигурации NuGet.Config в docker-контейнер. В качестве примера используем .NET CLI в Dockerfile для добавления источника.

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
ARG username
ARG pass
RUN dotnet nuget add source https://nuget.быстрыеотчеты.рф/api/v3/index.json --name fr_nuget --username $username --password $pass --store-password-in-clear-text

Теперь, при запуске команды docker build просто передадим необходимые параметры:

docker build -f "./DockerTestProject/Dockerfile" --force-rm --build-arg username=myaccount@fastreport.ru --build-arg pass=1234Password5678 -t dockertest:latest

Внимание! Данный способ передачи секретных ключей и паролей не безопасен. О более правильной передаче паролей как аргументов docker build можете почитать в соответствующем материале.

Обновление логин/пароля

Если данные от вашего аккаунта поменялись, то вам необходимо обновить их и в файле конфигурации NuGet. Рассмотрим следующие способы:

• .NET CLI;
• nuget.exe CLI;
• NuGet.Config.

В JetBrains Rider и Microsoft Visual Studio for Mac изменение пользовательских данных аналогично добавлению, с поправкой лишь на то, что необходимо обновить уже добавленный источник. В случае с подключением через Docker в вышеописанном способе добавления достаточно поменять пользовательские данные при сборке контейнера из Dockerfile.

.NET CLI:

(любая ОС, любой конфиг, любой вид хранения пароля)

Для работы данного способа необходимо иметь установленный SDK .NET Core 3.1.200 и выше (в том числе .NET 5 и выше). Впишем в командной строке:

dotnet nuget update source [имя ранее добавленного источника, например: fr_nuget] --username [email вашего аккаунта Быстрые отчеты] --password [пароль от вашего аккаунта Быстрые отчеты]

Подразумевается, что эта команда изменяет источник, который добавлен в глобальный NuGet.Config. Однако можно выбрать расположение файла конфигурации используя параметр --configfile (путь до файла конфигурации). По умолчанию, пароль от источника шифруется, для хранения пароля в незашифрованном виде используйте параметр --store-password-in-clear-text

Подробнее об этом способе обновления источника вы можете прочитать на сайте Microsoft.

Nuget.exe CLI:

(любая ОС (для macOS/Linux требуется Mono 4.4.2 или выше), любой конфиг, любой вид хранения пароля)

Установка nuget.exe подробно уже была ранее описана. Стоит рассмотреть лишь ключевые моменты.

nuget sources update -name [имя ранее добавленного источника, например: fr_nuget] -username [email вашего аккаунта Быстрые отчеты] -password [пароль от вашего аккаунта Быстрые отчеты]

Изначально эта команда изменяет источник, который добавлен в глобальный NuGet.Config. Однако можно выбрать расположение файла конфигурации используя параметр -ConfigFile (путь до файла конфигурации).

По умолчанию, пароль от источника шифруется, для хранения пароля в незашифрованном виде используйте параметр -StorePasswordInClearText.

Подробнее об этом способе обновления источника вы можете прочитать на сайте Microsoft.

Edit NuGet.Config:

(любая ОС, любой конфиг, не зашифрованный пароль)

Откроем необходимый файл конфигурации NuGet.Config любым текстовым редактором. В блоке ‘packageSourceCredentials’ с именем ранее добавленного источника изменим значения “Username” и “ClearTextPassword” на необходимые. Если вместо “ClearTextPassword” у вас блок “Password”, то просто замените его на “ClearTextPassword”. В итоге, должно выглядеть так:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
 <packageSources>
 <add key="FR-NuGet" value="https://nuget.быстрыеотчеты.рф/api/v3/index.json" />
 </packageSources>
 <packageSourceCredentials>
 <FR-NuGet>
 <add key="Username" value="myaccount@fastreport.ru" />
 <add key="ClearTextPassword" value="MyNewPassword5678" />
 </FR-NuGet>
 </packageSourceCredentials>
</configuration>

Подробнее о загрузке пакетов

По умолчанию, в интерфейсе вашей IDE вы видите все пакеты загруженные в приватный NuGet источник Быстрые отчеты. Однако для загрузки выбранного пакета должно соблюдаться следующие условие: если пакет не является общедоступным (такие как FastReport.Compat, демо версии пакетов FastReport.Core, FastReport.Net.Demo и т.д.), то вы должны обладать необходимой подпиской для загрузки последних версий этих пакетов.

К примеру, для загрузки FastReport.Core вы должны обладать подпиской не ниже FastReport .NET Standard (в том числе Professional, Enterprise или Ultimate), для загрузки FastCube.Core вы должны обладать подпиской не ниже FastCube .NET Standard (в том числе Professional или Ultimate) и т.д.

Восстановление пакетов в случае истекшей подписки

В случае окончания действия подписки вы можете продолжать пользоваться источником пакетов Быстрые отчеты, однако доступа к последним версиям пакетов не будет. Следовательно, последняя доступная версия пакета будет определяться по условию:

Дата выхода выбранной версии < дата истечения подходящей подписки

Важно! При попытке загрузки пакета с датой выхода позже, чем дата окончания подходящей подписки, Быстрые отчеты NuGet сервер отдаст самую последнюю доступную версию пакета согласно вашей подписке. Но мы не рекомендуем ссылку на недоступную версию пакета, т.к. это приводит к Warning при восстановлении проекта и к задержке загрузки пакета.