Table of Contents

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.