Built by Maven

dotnet:install

Full name:

de.eitco.cicd:dotnet-maven-plugin:1.0.1:install

Description:

This goal assumes the builds delivery artifacts to be located in the directory denoted by the goals `targetDirectory` parameter. It will simply copy all *.nupkg files located there to directory configured to be the local nuget directory.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is not marked as thread-safe and thus does not support parallel builds.
  • Binds by default to the lifecycle phase: install.

Optional Parameters

Name Type Since Description
<assemblyVersion> String - This parameter specifies the assembly version of this project. Keep in mind that the assembly version needs to consist of up to 4 numeric values separated by '.' e.g.: <major>.<minor>.<patch>.<build>.
<customProperties> Map<String,String> - This parameter specifies custom properties given to dotnet via '-p:'. Keep in mind that the 'Version', 'Company', 'Description', 'RepositoryUrl' and 'AssemblyVersion' properties will be overwritten by their respective parameters, when specified.
<dotnetExecutable> File - This parameter specifies the location of the dotnet executable. If not set dotnet being available by the PATH environment variable is assumed.
<dotnetSdkCacheBaseDirectory> String - This parameter specifies the base directory in which the versioned .NET SDK cache is located. It defaults to the local maven repository. Do not point it to a network file system, since the file locks used to synchronize concurrent builds are unreliable there.
Default: ${settings.localRepository}
User Property: dotnet.sdk.cacheBaseDirectory
<dotnetSdkCacheName> String - This parameter specifies the symbolic name of the local cache directory used to store .NET SDK versions downloaded because of dotnetSdkVersion. Analogous to localMavenNugetRepositoryName, the actual directory name is this value prefixed with ".".
The location of the cache directory can be configured with dotnetSdkCacheBaseDirectory.
Default: dotnet-sdk
User Property: dotnet.sdk.cacheName
<dotnetSdkProvisioningTimeoutSeconds> int - This parameter specifies the maximum time, in seconds, this plugin waits for a .NET SDK download/install (triggered by dotnetSdkVersion) to complete, including time spent waiting for a concurrently running build (in this or another process) that is already installing the same SDK version.
Default: 600
<dotnetSdkVersion> String - This parameter specifies the version or channel of the .NET SDK that this plugin should download and use, instead of relying on a dotnet installation already present on the system. If set, the plugin downloads the requested SDK into a per-version local cache directory (see dotnetSdkCacheName and dotnetSdkCacheBaseDirectory) using Microsoft's official dotnet-install script, without making any system-wide changes (no PATH modification, no registry entries). Subsequent builds requesting the same version reuse the cached installation without re-downloading it. The SDK is located at <dotnetSdkCacheBaseDirectory>/.<dotnetSdkCacheName>/<rid>/<version>, which defaults to ~/.m2/repository/.dotnet-sdk/<rid>/<version>. Concurrent builds - in this or other processes - that request the same version wait for each other, so the SDK is downloaded only once.

dotnet processes run with a managed SDK get environment variables that keep them from writing to the user's ~/.dotnet directory (DOTNET_NOLOGO, DOTNET_SKIP_FIRST_TIME_EXPERIENCE, DOTNET_GENERATE_ASPNET_CERTIFICATE=false, DOTNET_ADD_GLOBAL_TOOLS_TO_PATH=false, DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE). Each of them can be overridden with environmentVariables.

Exact versions (e.g. 8.0.424, 9.0.100, 9.0.100-preview.1): Downloads the exact SDK version specified. Use this for determinism.

Channel-style values (e.g. 8.0, 9.0, LTS, STS, latest, current): Downloads the latest patch of that channel. The version is pinned on first successful download into the cache directory (e.g. .../<rid>/8.0/); later upstream patches are not automatically picked up. To use latest patches, clear the cache or use an exact version.

This parameter is mutually exclusive with dotnetExecutable; configuring both fails the build immediately with a clear error message. If neither is set, dotnet being available via the PATH environment variable is assumed (this is the default, unchanged behaviour).


User Property: dotnet.sdk.version
<environmentVariables> Map<String,String> - This parameter specifies additional environment variables to be added to the dotnet process.
Note that the DOTNET_CLI_TELEMETRY_OPTOUT will be set to TRUE if not overwritten with this parameter.
<inlineRunSettings> Map<String,String> - This parameter lets you specify run settings that will be added to the dotnet command line. They will only be added to 'dotnet test'.
<localMavenNugetRepositoryBaseDirectory> String - This parameter specifies the location of the local nuget repository. The local nuget repository is a special file system repository this plugin copies the generated packages in the install phase to. This simulates mavens local repository.
Default: ${settings.localRepository}
<localMavenNugetRepositoryName> String - This parameter specifies the symbolic name of the local nuget repository. The local nuget repository is a special file system repository this plugin copies the generated packages in the install phase to. This simulates mavens local repository.
The location of the local nuget repository can be configured by localMavenNugetRepositoryBaseDirectory.
Default: maven-nuget-local
<nugetSources> Map<String,String> - This parameter specifies nuget sources to be added to the project. These are the locations where nuget will read dependencies from. The value of each entry is the url of the remote repository. The key is a unique name nuget will use to identify the repository by. It can also be used to add credentials to using <server> elements in the settings.xml.

Consider to encrypt passwords in your settings.xml

Note that crendentials added this way will be written to your nuget configuration file. On windows systems the credentials will be encrypted, however on linux systems password encryption is not supported by nuget - so the credentials will be written to the {code nuget} config way unencrypted.

<projectVersion> String - This parameter specifies the version of this project given to dotnet by the -p:Version= command line parameter.
Default: ${project.version}
<skip> boolean - No description.
Default: false
<snapshotReplacement> String - This parameter specifies the replacement of the suffix '-SNAPSHOT' in version properties
Default: -build.%c
<targetDirectory> File - This parameter specifies the directory where dotnet writes its generated package(s) to.
Default: ${project.build.directory}/dot-net
<vendor> String - This parameter specifies the Company added to the compiles executables or libraries.
Default: ${project.organization.name}
<versionProperties> Map<String,String> - This parameter specifies properties that contain versions. They will be handled differently than normal properties to honour '-SNAPSHOT' dependencies. This happens in two steps per property:
  1. it is checked whether the property value ends with '-SNAPSHOT'
    • if not the value of the property is used
    • if it does end with '-SNAPSHOT' the ending substring '-SNAPSHOT' is replaced with the value of the parameter snapshotReplacement
  2. it is checked if the resulting string contains the string '%c'
    • if not this is the value used
    • if yes, the string will represent a version range: the minimum element is the string with every occurrence of '%c' replaced by '0', the (excluded) upper bound will be the string with every occurrence of '%c' replaced by 'A'

For example this configuration:

<versionProperties>
  <apacheVersion>3.1.4</apacheVersion>
  <someMavenDependencyVersion>1.5.6-dev-version-addendum-SNAPSHOT</someMavenDependencyVersion>
</versionProperties>

would result in two dotnet properties, referable with '$()' so that

$(apacheVersion) = 3.1.4
$(someMavenDependencyVersion) = [1.5.6-dev-version-addendum-build.0,1.5.6-dev-version-addendum-build.A)
<workingDirectory> File - This parameter specifies the directory where to execute dotnet and thus where the project files are located
Default: ${project.basedir}

Parameter Details

<assemblyVersion>

This parameter specifies the assembly version of this project. Keep in mind that the assembly version needs to consist of up to 4 numeric values separated by '.' e.g.: <major>.<minor>.<patch>.<build>.
  • Type: java.lang.String
  • Required: No

<customProperties>

This parameter specifies custom properties given to dotnet via '-p:'. Keep in mind that the 'Version', 'Company', 'Description', 'RepositoryUrl' and 'AssemblyVersion' properties will be overwritten by their respective parameters, when specified.
  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Required: No

<dotnetExecutable>

This parameter specifies the location of the dotnet executable. If not set dotnet being available by the PATH environment variable is assumed.
  • Type: java.io.File
  • Required: No

<dotnetSdkCacheBaseDirectory>

This parameter specifies the base directory in which the versioned .NET SDK cache is located. It defaults to the local maven repository. Do not point it to a network file system, since the file locks used to synchronize concurrent builds are unreliable there.
  • Type: java.lang.String
  • Required: No
  • User Property: dotnet.sdk.cacheBaseDirectory
  • Default: ${settings.localRepository}

<dotnetSdkCacheName>

This parameter specifies the symbolic name of the local cache directory used to store .NET SDK versions downloaded because of dotnetSdkVersion. Analogous to localMavenNugetRepositoryName, the actual directory name is this value prefixed with ".".
The location of the cache directory can be configured with dotnetSdkCacheBaseDirectory.
  • Type: java.lang.String
  • Required: No
  • User Property: dotnet.sdk.cacheName
  • Default: dotnet-sdk

<dotnetSdkProvisioningTimeoutSeconds>

This parameter specifies the maximum time, in seconds, this plugin waits for a .NET SDK download/install (triggered by dotnetSdkVersion) to complete, including time spent waiting for a concurrently running build (in this or another process) that is already installing the same SDK version.
  • Type: int
  • Required: No
  • Default: 600

<dotnetSdkVersion>

This parameter specifies the version or channel of the .NET SDK that this plugin should download and use, instead of relying on a dotnet installation already present on the system. If set, the plugin downloads the requested SDK into a per-version local cache directory (see dotnetSdkCacheName and dotnetSdkCacheBaseDirectory) using Microsoft's official dotnet-install script, without making any system-wide changes (no PATH modification, no registry entries). Subsequent builds requesting the same version reuse the cached installation without re-downloading it. The SDK is located at <dotnetSdkCacheBaseDirectory>/.<dotnetSdkCacheName>/<rid>/<version>, which defaults to ~/.m2/repository/.dotnet-sdk/<rid>/<version>. Concurrent builds - in this or other processes - that request the same version wait for each other, so the SDK is downloaded only once.

dotnet processes run with a managed SDK get environment variables that keep them from writing to the user's ~/.dotnet directory (DOTNET_NOLOGO, DOTNET_SKIP_FIRST_TIME_EXPERIENCE, DOTNET_GENERATE_ASPNET_CERTIFICATE=false, DOTNET_ADD_GLOBAL_TOOLS_TO_PATH=false, DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE). Each of them can be overridden with environmentVariables.

Exact versions (e.g. 8.0.424, 9.0.100, 9.0.100-preview.1): Downloads the exact SDK version specified. Use this for determinism.

Channel-style values (e.g. 8.0, 9.0, LTS, STS, latest, current): Downloads the latest patch of that channel. The version is pinned on first successful download into the cache directory (e.g. .../<rid>/8.0/); later upstream patches are not automatically picked up. To use latest patches, clear the cache or use an exact version.

This parameter is mutually exclusive with dotnetExecutable; configuring both fails the build immediately with a clear error message. If neither is set, dotnet being available via the PATH environment variable is assumed (this is the default, unchanged behaviour).

  • Type: java.lang.String
  • Required: No
  • User Property: dotnet.sdk.version

<environmentVariables>

This parameter specifies additional environment variables to be added to the dotnet process.
Note that the DOTNET_CLI_TELEMETRY_OPTOUT will be set to TRUE if not overwritten with this parameter.
  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Required: No

<inlineRunSettings>

This parameter lets you specify run settings that will be added to the dotnet command line. They will only be added to 'dotnet test'.
  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Required: No

<localMavenNugetRepositoryBaseDirectory>

This parameter specifies the location of the local nuget repository. The local nuget repository is a special file system repository this plugin copies the generated packages in the install phase to. This simulates mavens local repository.
  • Type: java.lang.String
  • Required: No
  • Default: ${settings.localRepository}

<localMavenNugetRepositoryName>

This parameter specifies the symbolic name of the local nuget repository. The local nuget repository is a special file system repository this plugin copies the generated packages in the install phase to. This simulates mavens local repository.
The location of the local nuget repository can be configured by localMavenNugetRepositoryBaseDirectory.
  • Type: java.lang.String
  • Required: No
  • Default: maven-nuget-local

<nugetSources>

This parameter specifies nuget sources to be added to the project. These are the locations where nuget will read dependencies from. The value of each entry is the url of the remote repository. The key is a unique name nuget will use to identify the repository by. It can also be used to add credentials to using <server> elements in the settings.xml.

Consider to encrypt passwords in your settings.xml

Note that crendentials added this way will be written to your nuget configuration file. On windows systems the credentials will be encrypted, however on linux systems password encryption is not supported by nuget - so the credentials will be written to the {code nuget} config way unencrypted.

  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Required: No

<projectVersion>

This parameter specifies the version of this project given to dotnet by the -p:Version= command line parameter.
  • Type: java.lang.String
  • Required: No
  • Default: ${project.version}

<skip>

No description.
  • Type: boolean
  • Required: No
  • Default: false

<snapshotReplacement>

This parameter specifies the replacement of the suffix '-SNAPSHOT' in version properties
  • Type: java.lang.String
  • Required: No
  • Default: -build.%c

<targetDirectory>

This parameter specifies the directory where dotnet writes its generated package(s) to.
  • Type: java.io.File
  • Required: No
  • Default: ${project.build.directory}/dot-net

<vendor>

This parameter specifies the Company added to the compiles executables or libraries.
  • Type: java.lang.String
  • Required: No
  • Default: ${project.organization.name}

<versionProperties>

This parameter specifies properties that contain versions. They will be handled differently than normal properties to honour '-SNAPSHOT' dependencies. This happens in two steps per property:
  1. it is checked whether the property value ends with '-SNAPSHOT'
    • if not the value of the property is used
    • if it does end with '-SNAPSHOT' the ending substring '-SNAPSHOT' is replaced with the value of the parameter snapshotReplacement
  2. it is checked if the resulting string contains the string '%c'
    • if not this is the value used
    • if yes, the string will represent a version range: the minimum element is the string with every occurrence of '%c' replaced by '0', the (excluded) upper bound will be the string with every occurrence of '%c' replaced by 'A'

For example this configuration:

<versionProperties>
  <apacheVersion>3.1.4</apacheVersion>
  <someMavenDependencyVersion>1.5.6-dev-version-addendum-SNAPSHOT</someMavenDependencyVersion>
</versionProperties>

would result in two dotnet properties, referable with '$()' so that

$(apacheVersion) = 3.1.4
$(someMavenDependencyVersion) = [1.5.6-dev-version-addendum-build.0,1.5.6-dev-version-addendum-build.A)
  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Required: No

<workingDirectory>

This parameter specifies the directory where to execute dotnet and thus where the project files are located
  • Type: java.io.File
  • Required: No
  • Default: ${project.basedir}