Consume packages
Configuring the NuGet source
By default, NuGet commands executed by Neos try to find a dependencies.nuget.config
file in your cluster modules
directory.
Creating this file, which does not have the default name nuget.config
, avoids any conflict with the sources used by dotnet
.
If this file does not exist, NuGet commands executed by Neos will use user or machine specific configuration (more details).
We advice you to add a dependencies.nuget.config
file in your cluster modules
directory. This is considered a best practice as it promotes repeatability and ensures that different users have the same NuGet configuration. You may need to configure clear elements to ensure no user or machine specific configuration is applied (more details).
Below is an example of a configuration file that deletes all the default sources and adds the source containing the shared modules:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="XYZ" value="https://pkgs.dev.azure.com/pole-erp-groupeisa/fmk/_packaging/XYZ/nuget/v3/index.json" />
</packageSources>
</configuration>
Link to documentation for Azure DevOps sources
Configuring the cluster
To use modules from NuGet in your cluster, you need to list them in the ReferencedModules
section in your cluster configuration.
Each module must be identified by its name and a version number.
Note
As with the NuGet packages you use in Visual Studio, it is not necessary to explicitly reference a package's dependencies. If a package depends on another package, it will automatically be retrieved as well.
The example below shows how to reference the Party and UserPermissions modules in version 1.15.4:
ReferencedModules:
Party: 1.15.4
UserPermissions: 1.15.4
You can place this content in an existing yaml file in the cluster's root directory or insert it in a new one (for example mycluster.referenced-modules.yml).
Restoring packages
You can restore packages explicitly by calling neos restore
.
Note
Restore is also performed automatically by neos generate
unless the --restore false
option has been passed.
Restoration automatically populates the modules/dependencies
directory.
Warning
Before packages were introduced, the dependencies
directory was populated manually. When you switch to packages mode, it is forbidden to modify it manually. We strongly advise against mixing manually managed dependencies with package-managed dependencies.
Restoration creates a {ModuleName}.{ModuleVersion}
folder in the dependencies
directory for each module referenced directly or indirectly.
If we take the example of the references to Party and UserPermissions modules in version 1.15.4, the dependencies
folder could look like this:
modules
└───dependencies
└───Communication.1.15.4
└───Core.1.15.4
└───Party.1.15.4
└───RegionalSettings.1.15.4
└───Shared.1.15.4
└───UserPermissions.1.15.4
references.yml
Note
Modules Communication, Core, RegionalSettings and Shared are present because they are referenced by Party and/or UserPermissions modules.
The references.yml
file caches the list of modules referenced directly during the last restore.
In the example above, it therefore contains :
- Name: Party
Version: 1.15.4
- Name: UserPermissions
Version: 1.15.4
This file is used to quickly detect whether the references are up to date. When a difference is detected (new dependency, deleted dependency, version modification), the restore process re-synchronizes the dependencies
directory.
This file must always be consistent with the contents of the dependencies
directory. For this reason, we strongly advise against making manual changes to this folder.
If you have any doubts about its contents, delete the dependencies
directory completely before restarting a restore.
How Neos version control works during restoration
When a module is published as a package, the Neos version is stored in the package metadata as a tag (example: neos:1.16.0).
When restoring a package from a cluster using Neos version X.Y.Z, a check is made to authorize restoration only if the package was generated from a Neos version X.Y.*.
This control avoids restoring package versions that are not compatible with the version of Neos you are using.
If you want to disable this control (for testing purposes, for example), you can add these lines to your cluster configuration:
RestoreOptions:
IgnoreNeosVersion: true
How the NuGet package cache is managed
By default, the local cache of NuGet packages is located here: %USERPROFILE%/.nuget/packages
.
To avoid any risk of naming conflicts with NuGet packages that are not modules, the NuGet commands executed by Neos to restore modules use a different local cache: %USERPROFILE%/.neos/packages
.
This cache can be safely deleted.
How metadata migration is managed
The restore process does not support metadata migration. If, after retrieving a module, you get a metadata version error, you need to run the following command manually:
neos migrate-metadata
This command supports all modules whether they are in the root of modules
or in modules/dependencies
.
How to consume local modules
Since version 1.20, it is possible to reference a local module by defining its path :
ReferencedModules:
Party: ../Northwind/modules/Party
UserPermissions: ../Westwater/modules/UserPermissions
The path must be relative to the cluster directory. Absolute paths are not supported.
The restoration will create a symbolic link in the modules/dependencies
directory pointing to the module directory.
Warning
If the local module has dependent modules in the same cluster, symbolic links for these dependent modules will also be created. However, if the dependent modules come from NuGet packages, they will not be retrieved.