Package References

Elements supports NuGet (.NET) and Gradle/Maven (Java and Android) package references to automatically download and maintain dependencies for your projects on these platforms.

While these were supported to a limited degree in Elements 9 and earlier, the remainder of this topic focuses on how Package References work in Elements 10 and later, when using EBuild, since for EBuild we have completely revamped the package management system, and EBuild now handles all package resolving internally, without relying on NuGet or Gradle to be installed.

NuGet and Gradle

EBuild handles both NuGet and Gradle package references very similar, so a lot of the things discussed in this topic apply equally to both kinds of packages.

  • NuGet packages are supported on the .NET platform when targeting the full .NET framework, .NET Standard and .NET Core.

  • Gradle packages are supported on the Java platform, and most commonly used with the Android platform (but also available for plain Java projects, as well).

Names and Versions

A Package reference is specified as a combination of a name and a version, separated by colon. For example: com.android.support:support-v4:22.2.1.

Version numbers can be specified in several formats:

  • A simple asterisk ("*") will request any available version and pick the latest non-beta version.
  • A simple version number ("5.0") will request that version or higher, excluding any pre-release builds (e.g, "5.1", but not "5.2-alpha").
  • A simple version number with pre-release suffix ("5.0-beta") will request that version or higher, including pre-release builds.
  • A range of two versions separated by comma will pick the best version in that range:
    • "2.0,4.0" would pick any version starting from 2.0
    • A trailing ] will restrict request the exact version (2.0,3.0] would pick the best version starting from 2.0, up and and including 3.0 (but not 3.1)
    • A trailing ) will restrict request the highest version below the specified number (2.0,3.0) would pick the highest 2.x version (but not 3.x).

In general, Semantic Versioning rules will be used.

Recursive Dependencies

Package references can have recursive dependencies to further packages (e.g. package "A" might depend on package "B"). EBuild will automatically resolve all recursive dependencies until every necessary reference is pulled in. If references to different versions of the same package are encountered, EBuild will automatically upgrade to use the highest required version, where possible.

Result of Package Reference Resolving

The final result of package resolving will be one or more Plain References that will be processed like any direct reference would. These can be .dll files on .NET, or .jar and .aar files, on Java/Android.

Fire and Water will expand Project references in the Solution Tree to show you the final plain references that resulted from them, and also show you any dependent recursive references, a well:

Repositories

By default, packages will be resolved from the default platform vendor's repositories. For .NET, that is the central repository at api.nuget.org. For Android, that are maven.google.com, repo1.maven.org/maven2 and jcenter.bintray.com, as well as any local repositories in disk in the extras folder of the Android SDK install.

Additional custom repositories can be configured locally within the project by adding one or more repository object, such as:

  • <NuGetRepository Include="https://www.example.org/nuget" />
  • <GradleRepository Include="https://www.example.org/maven" />

Per-Reference Repositories

Sometimes, it is useful to specify custom repository for a specific reference, to override where this package will be obtained from. This can be done by providing the URL of the repository as metadata for the package reference elements, using the NugetRepository or GradpeRepository name, respectively.

If a repository is specified here, it will be checked first, before looking in the other standard (or per-project) repositories. (The local cache will still be consulted before).

<NuGetReference Include="MyPackage:*">
  <NuGetRepository>https://www.example.org/nuget</NuGetRepository>
  <Private>True</Private>
</NuGetReference>

or

<GradleReference Include="myorg:mypackage:*">
  <GradleRepository>https://www.example.org/maven</GradleRepository>
  <Private>True</Private>
</GradleReference>

Caching

Packages downloaded from remote repositories will be cached locally in a central storage shared by all EBuild projects. You can build with the --no-package-cache command line switch to disable any caching and re-download all repositories fresh from the server.

Adding Package References

You can add Package References to your project from Fire and Water via the fourth tab of the Manage References dialog, which can be accessed from the "Project" menu, by right-clicking the "References" node or by pressing ^⇧R (Fire) or Shift-Alt-R (Water):

You can also manually add package reference elements to your project file, e.g.:

  • <NuGetReference Include="Microsoft.NETCore.App:*" />
  • <GradleReference Include="com.android.support:support-v4:22.2.1" />

See Also