W artykule na temat pracy z pakietami NuGet rozważaliśmy wszystkie specyficzne cechy korzystania z oprogramowania Fast Reports. Jednym z najczęstszych pytań naszych klientów jest następujące:
Jak zainstalować wasze pakiety licencyjne w naszym produkcie używając Linux, MacOS lub Windows, aby nie musieć instalować najnowszej aktualizacji produktów FastReport ręcznie przez instalator pobrany ze strony internetowej kompatybilny tylko z Windows?
Aby odpowiedzieć na to pytanie, przygotowaliśmy kompleksowe rozwiązanie takie jak nasz Fast Reports Private NuGet-server.
Co to jest i do czego służy?
Prawie wszystkie pakiety, których używasz w swoich projektach są przechowywane w publicznym rejestrze pakietów NuGet Gallery (nuget.org). Można tam znaleźć różne wersje demonstracyjne naszych pakietów, jednak nie ma pełnych pakietów, które nie byłyby ograniczone wersjami demonstracyjnymi. Dlatego zdecydowaliśmy się stworzyć nasz rejestr pakietów dostępny tylko dla klientów Fast Reports. Dlatego też, aby mieć do niego dostęp, musisz posiadać konto Fast Reports (poprzez to konto możesz przejść na stronę cpanel.fast-report.com w celu pobrania instalatora produktu).
Dodawanie źródła
Rozważamy kilka rodzajów dodania naszego NuGet-serwera:
Na początku jednak należy omówić różnice pomiędzy globalnym a lokalnym NuGet Config.
Globalny i lokalny NuGet.Config
Należy rozważyć przywrócenie pakietów używanych w projekcie:
1) NuGet szuka potrzebnych pakietów w cache
2) NuGet szuka potrzebnych pakietów we wszystkich źródłach dodanych do pliku NuGet.Config, oraz:
a) Adresy NuGet do lokalnego NuGet.Config
b) Adresy NuGet do globalnego NuGet.Config
Lokalny NuGet.Config znajduje się w pobliżu twojego projektu. Tak więc źródła, które zostały dodane tutaj będą używane tylko do przywracania tego projektu.
Z kolei globalny NuGet.Config będzie używany dla wszystkich projektów tego komputera. Nie jest to jednak konieczne dla wszystkich projektów.
Globalna lokalizacja NuGet.Config:
Windows: "C:\Users\{User’s_name }\AppData\Roaming\NuGet\NuGet.Config"
MacOS: "~/.config/NuGet/NuGet.Config"
Linux: “~/.config/NuGet/NuGet.Config”
I tak, zgodnie ze specyfikacją NuGet, nazwa serwera, jego adres oraz Twoje dane (email i hasło do tego serwera) muszą być zapisane w pliku o nazwie NuGet.Config (lub nuget.config), który będzie znajdował się w odpowiednim dla Ciebie miejscu.
Szyfrowane i nieszyfrowane przechowywanie haseł
Plik NuGet.Config jest w stanie przechowywać hasło źródłowe w sposób zaszyfrowany jak również w formacie ClearTextPassword. W większości przypadków zalecane jest przechowywanie haseł zaszyfrowanych, jednak jednocześnie szyfrowanie odbywa się przy pomocy parametrów środowiska zewnętrznego (system operacyjny, konfiguracja komputera, itp.). W konsekwencji, jeżeli rozprowadzimy ten plik konfiguracyjny na inną maszynę, to wspomniane hasło nie będzie mogło zostać rozszyfrowane i nie uzyskamy dostępu do źródła. Należy wziąć to pod uwagę przy wyborze rodzaju dodawania lub aktualizacji źródła.
Następnie zapoznamy się z głównymi metodami dodawania naszego źródła do NuGet wraz z określeniem systemu operacyjnego kompatybilnego z daną metodą. Dodatkowo nie zapomnimy o dostępnych typach konfiguracji oraz formacie przechowywania hasła źródłowego.
.NET CLI:
(dowolny OS, dowolna konfiguracja, dowolny format zapisu hasła)
Pobrane SDK .NET Core 3.1.200 i późniejsze (w tym SDK .NET 5 i późniejsze) jest konieczne, aby ta metoda zadziałała. Umieść w wierszu poleceń:
dotnet nuget add source https://nuget.fast-report.com/api/v3/index.json --name [wybierz nazwę źródła bez spacji, na przykład: fr_nuget] --username [email Twojego konta Fast Reports] --password [hasło z Twojego konta Fast Reports]
Domyślnie polecenie to dodaje źródło do globalnego NuGet.Config, ale można wybrać lokalizację pliku konfiguracyjnego i uczynić go lokalnym za pomocą parametru --configfile [ścieżka pliku konfiguracyjnego].
Hasło źródłowe jest również domyślnie zaszyfrowane, a parametr --store-password-in-clear-text jest niezbędny do przechowywania niezaszyfrowanego hasła.
Przykład:
dotnet nuget add source https://nuget.fast-report.com/api/v3/index.json --name fr_nuget --username myaccount@fast-report.com --password 1234Password5678
Możesz przeczytać więcej o tej metodzie dodawania źródła na stronie internetowej firmy Microsoft.
Microsoft Visual Studio:
(Windows, globalny config, zaszyfrowane hasło )
Rozważ dodanie NuGet-server za pomocą Microsoft Visual Studio 2022 na przykładzie. Ważne jest, aby wziąć pod uwagę, że ta metoda działa począwszy od Visual Studio 2017. W menu wybieramy "Tools", następnie "NuGet Package Manager" i otwieramy okno "Package Manager Settings".
Następnie po lewej stronie wybieramy 'Źródła pakietów' i klikamy przycisk + (dodaj).
Wpisz nazwę źródła w polu 'Name' bez spacji (np. FastReport-NuGet) oraz adres źródła https://nuget.fast-report.com/api/v3/index.json w polu 'Source'.
Naciśnij 'ОК', a następnie przejdź do okna dodawania pakietów.
Z listy rozwijanej 'Źródło pakietu' wybieramy źródło, które właśnie dodaliśmy. Następnie w oknie dialogowym wypełniamy dane konta Fast Reports i zaznaczamy 'Pamiętaj moje hasło'.
Microsoft Visual Studio for Mac:
(macOS, konfiguracja globalna, hasło szyfrowane)
Rozważmy na przykładzie Microsoft Visual Studio for Mac 2019.
W menu wybieramy 'Project' i otwieramy okno 'Manage NuGet Packages...'.
Na dole listy rozwijanej "Źródło pakietów" wybierz "Konfiguruj źródła...".
Naciśnij przycisk Dodaj i wypełnij dane w oknie:
- Nazwa: nazwa źródła bez spacji (np. FastReport-Nuget);
- Lokalizacja: https://nuget.fast-report.com/api/v3/index.json ;
- Nazwa użytkownika: email z konta Fast Reports;
- Hasło: hasło z konta Fast Reports.
Potwierdź dodanie źródła przyciskiem 'Dodaj źródło'.
JetBrains Rider:
(dowolny system operacyjny, globalna konfiguracja, szyfrowane hasło)
Rozważmy na przykładzie Rider 2021.3 w systemie Linux Ubuntu 18.04.
Przejdź do menu 'Tools', 'NuGet' i wybierz 'Show NuGet Sources'.
Naciśnij + w oknie NuGet w 'Sources' przed 'New feed'.
Wprowadź niezbędne dane:
- Nazwa - nazwa źródła bez spacji (np. FastReport-Nuget);
- URL - https://nuget.fast-report.com/api/v3/index.json ;
- Użytkownik - email z konta Fast Reports;
- Hasło - hasło z konta Fast Reports.
Nuget.exe CLI:
(dowolny OS (Mono 4.4.2 lub nowsze jest wymagane dla macOS/Linux), dowolny config, dowolny typ zapisu hasła)
Instalacja Nuget.exe jest szczegółowo opisana na stronie Microsoftu. Teraz zajmiemy się tylko ważnymi funkcjami.
nuget sources add -name [wybierz nazwę źródła bez spacji, na przykład: fr_nuget] -source"https://nuget.fast-report.com/api/v3/index.json" -username [email Twojego konta w Fast Reports] - password [hasło do konta Fast Reports]
Domyślnie polecenie to dodaje źródło w globalnym NuGet.Config, jednakże można wybrać lokalizację pliku konfiguracyjnego i uczynić go lokalnym używając parametru -ConfigFile (ścieżka do pliku konfiguracyjnego).
Początkowo hasło źródłowe jest zaszyfrowane, a parametr -StorePasswordInClearText służy do przechowywania niezaszyfrowanego hasła.
Przykład:
nuget sources add -name fr_nuget -source “https://nuget.fast-report.com/api/v3/index.json” -username myaccount@fast-report.com -password 1234Password5678
Możesz przeczytać więcej o tej metodzie dodawania źródła na stronie internetowej firmy Microsoft.
Edit NuGet.Config:
(dowolny OS, dowolny config, nieszyfrowane hasło)
Ważne! Za pomocą tej metody można wprowadzić tylko niezaszyfrowane hasło z konta Fast Reports, ponieważ plik konfiguracyjny jest prostym plikiem XML. Można go otworzyć lub utworzyć w dowolnym edytorze tekstu. W bloku 'packageSources' należy dodać nasz zasób o wybranej nazwie (niepożądane jest używanie spacji), np:
<add key="FR-NuGet" value="https://nuget.fast-report.com/api/v3/index.json" />
W bloku 'packageSourceCredentials' należy dodać swój email i hasło z konta Fast Reports w bloku z tym samym kluczem:
<FR-NuGet> <add key="Username" value="myaccount@fast-report.com" /> <add key="ClearTextPassword" value="1234Password5678" /> </FR-NuGet>
Na koniec otrzymasz podobny plik konfiguracyjny (inne źródła zostały usunięte z przykładu):
<?xml version="1.0" encoding="utf-8"?> <configuration> <packageSources> <add key="FR-NuGet" value="https://nuget.fast-report.com/api/v3/index.json" /> </packageSources> <packageSourceCredentials> <FR-NuGet> <add key="Username" value="myaccount@fast-report.com" /> <add key="ClearTextPassword" value="1234Password5678" /> </FR-NuGet> </packageSourceCredentials> </configuration>
Docker:
(dowolny OS, dowolna konfiguracja, nieszyfrowane hasło )
W Dockerfile podczas tworzenia docker-image należy dodać źródło albo za pomocą .NET CLI, albo poprzez umieszczenie w docker-container przygotowanego wcześniej pliku konfiguracyjnego NuGet.Config. Jako przykład użyjemy .NET CLI w Dockerfile aby dodać źródło.
FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build ARG username ARG pass RUN dotnet nuget add source https://nuget.fast-report.com/api/v3/index.json --name fr_nuget --username $username --password $pass --store-password-in-clear-text
Teraz uruchamiając komendę docker build podajemy tylko niezbędne parametry:
docker build -f "./DockerTestProject/Dockerfile" --force-rm --build-arg username=myaccount@fast-report.com --build-arg pass=1234Password5678 -t dockertest:latest
Uwaga! Ta metoda przesyłania kluczy prywatnych i haseł nie jest bezpieczna. Możesz przeczytać odpowiedni artykuł na temat bezpieczniejszego przekazywania haseł jako argumentów budowy dockera.
Aktualizacja loginu/hasła
Jeśli dane konta uległy zmianie, musisz zaktualizować je w pliku konfiguracyjnym NuGet. Rozważ następujące metody:
- .NET CLI;
- nuget.exe CLI;
- NuGet.Config.
W JetBrains Rider i Microsoft Visual Studio for Mac zmiana danych użytkownika jest podobna do dodawania, jedyną korektą jest konieczność aktualizacji źródła, które już dodaliśmy. W przypadku połączenia przez Dockera w sposób opisany powyżej wystarczy zmienić dane użytkownika przy składaniu kontenera z pliku Dockerfile.
.NET CLI:
(dowolny system operacyjny, dowolna konfiguracja, dowolna metoda przechowywania haseł)
Zainstalowane SDK .NET Core 3.1.200 i późniejsze (w tym.NET 5 i późniejsze) jest konieczne, aby ta metoda zadziałała. Umieść w wierszu poleceń:
dotnet nuget update source [nazwa zasobu, który został dodany wcześniej, na przykład: fr_nuget] --username [email Twojego konta Fast Reports] --password [hasło Twojego konta Fast Reports]
To polecenie jest traktowane jako zmiana źródła, które zostało dodane do globalnego NuGet.Config. Jednakże, możesz wybrać lokalizację pliku konfiguracyjnego używając parametru --configfile (ścieżka do pliku konfiguracyjnego). Domyślnie, hasło źródła jest zaszyfrowane, możesz użyć parametru --store-password-in-clear-text aby przechowywać niezaszyfrowane hasło
Możesz przeczytać więcej o tej metodzie aktualizacji źródła na stronie internetowej firmy Microsoft.
Nuget.exe CLI:
(dowolny OS (dla macOS/Linux wymagane jest Mono 4.4.2 lub nowsze), dowolny config, dowolny typ zapisu hasła)
Instalacja Nuget.exe została wcześniej szczegółowo opisana. W tym miejscu wystarczy tylko zwrócić uwagę na najważniejsze cechy.
nuget sources update -name [nazwa źródła, które zostało dodane wcześniej, na przykład: fr_nuget] -username [email Twojego konta Fast Reports] -password [hasło Twojego konta Fast Reports]
Początkowo polecenie to zmienia źródło dodane w globalnym NuGet.Config. Można jednak wybrać lokalizację pliku konfiguracyjnego za pomocą parametru -ConfigFile (ścieżka do pliku konfiguracyjnego).
Domyślnie hasło jest zaszyfrowane, parametr -StorePasswordInClearText służy do przechowywania niezaszyfrowanego hasła.
Możesz przeczytać więcej o tej metodzie aktualizacji źródła na stronie internetowej firmy Microsoft.
Edit NuGet.Config:
(dowolny OS, dowolny config, nie szyfrowane hasło )
Otwieramy potrzebny plik NuGet.Config za pomocą dowolnego edytora tekstowego. W bloku "packageSourceCredentials" z nazwą źródła, które zostało dodane wcześniej zmieniamy wartości "Username" i "ClearTextPassword" na potrzebne. Jeśli zamiast "ClearTextPassword" mamy blok "Password", wystarczy zmienić go na "ClearTextPassword". Ostatecznie powinno to wyglądać tak, jak poniżej:
<?xml version="1.0" encoding="utf-8"?> <configuration> <packageSources> <add key="FR-NuGet" value="https://nuget.fast-report.com/api/v3/index.json" /> </packageSources> <packageSourceCredentials> <FR-NuGet> <add key="Username" value="myaccount@fast-report.com" /> <add key="ClearTextPassword" value="MyNewPassword5678" /> </FR-NuGet> </packageSourceCredentials> </configuration>
Więcej szczegółów na temat pobierania pakietów
Domyślnie, w interfejsie Twojego IDE widzisz wszystkie pakiety pobrane w Fast Reports z prywatnego źródła NuGet. Jednakże, aby pobrać wybrany pakiet należy spełnić kolejny warunek: jeżeli pakiet nie jest dostępny publicznie (np. FastReport.Compat, FastReport.Core wersja demo, FastReport.Net.Demo, itd.), musisz posiadać niezbędną subskrypcję, aby móc pobierać najnowsze aktualizacje tych pakietów.
Na przykład, aby pobrać FastReport.Core musisz mieć subskrypcję nie wcześniejszą niż FastReport .NET Standard (w tym Professional, Enterprise lub Ultimate), aby pobrać FastCube.Core musisz mieć subskrypcję nie wcześniejszą niż FastCube .NET Standard (w tym Professional lub Ultimate), itd.
Restoring packages in case of an expired subscription
Jeśli Twoja subskrypcja wygasła, możesz nadal korzystać ze źródła pakietów Fast Reports, jednak nie będziesz miał dostępu do najnowszych wersji pakietów. W konsekwencji, najnowsza dostępna wersja pakietu będzie określana na podstawie następującego warunku:
Data wydania wybranej wersji < data wygaśnięcia niezbędnej subskrypcji
Ważne! W przypadku próby pobrania pakietu z datą wydania późniejszą niż wymagana data wygaśnięcia subskrypcji, serwer Fast Reports NuGet dostarczy najnowszą dostępną wersję pakietu w oparciu o posiadaną subskrypcję. Nie zalecamy jednak umieszczania linku do niedostępnej wersji pakietu, gdyż prowadzi to do powiadomienia o ostrzeżeniu podczas przywracania projektu oraz opóźnienia w pobieraniu pakietu.
