Most of the command lines below need to be run with administrative rights. As RealmJoin itself will install Chocolatey and machine Craft packages from within the System context, the command lines can also be run from a system command prompt to resemble the production situation as close as possible. To open a system command prompt, the tool
psexecfrom the Windows Sysinternals tools can be used:
psexec /d /i /s cmd.exe
In some cases, it may be necessary to update to the latest version of the RealmJoin core extension for the latest development features to become available:
choco upgrade realmjoin-core.extension -y --force
To test a Chocolatey package from the source without packing, building or deploying it, a helper within the RealmJoin core extension can be used. Change to the folder where the package sources are located (i.e. where the
.nuspecfile is located) and run the following command (as administrator):
This command will also accept parameters like
-uninstall(to uninstall instead of installing) and
-params(to pass args like they would be specified in the RealmJoin back-end package definition).
Also, the contents of the
blobsfolder will automatically be copied to the temporary location where they would normally be downloaded to. Therefore the download of blob files from the RealmJoin CDN might fail (in case a file has never been deployed to the CDN), but the installation should still complete successfully as Chocolatey will detect that a file with the correct name and checksum is already available locally.
Except for very specific cases, this command should also work from a folder shared with a virtual machine from outside (e.g. VMware Shared Folders or local drives shared with Hyper-V guests in enhanced session mode). This might be helpful if package development and testing are done on two different (virtual) machines.
In specific cases (if the
blobsfolder is not being used at all or if it's contents have already been deployed to the RealmJoin CDN before, see above), a package can also be packed locally for testing by running the following command from the folder where the
.nuspecfile is located:
On the testing machine, a normal file system folder can be added as a Chocolatey repository, e.g.:
choco source add -n=rjlocaltemp -s"c:\temp"
The resulting package (
.nupkg) from step 1 can then be copied to this folder and be installed by Chocolatey natively:
choco install customername-packagename -y --force
To import all Chocolatey and RealmJoin cmdlets into a PowerShell session, the following PowerShell command can be used:
Import-Module "$env:ProgramData\chocolatey\helpers\chocolateyInstaller.psm1"This will also import the RealmJoin core extension module and can be useful to run some of its cmdlets interactively, e.g.
If run with administrative rights, there are a few more development cmdlets available to load package information from a
.nuspecfile and to even run a Chocolatey script (e.g.
chocolateyInstall.ps1) directly from within the PowerShell session:
Initialize-RealmjoinChocoDevChocoEnvironment [[-nuspecFile] <string>] [[-packageName] <string>] [[-packageVersion] <string>] [[-packageTitle] <string>] [[-packageFolder] <string>] [[-params] <string>] [<CommonParameters>]
Invoke-RealmjoinChocoDevScript [[-scriptToRun] <string>] [[-params] <Object>] [-uninstall] [-copyBlobs]
For further details, please take a look at the files in
%ProgramData%\chocolatey\lib\realmjoin-core.extensionand specifically at the code in the following files:
A short summary of how the RealmJoin packaging team usually handles software updates and/or uninstalls when packaging software:
- We do not expect uninstalls to be generally really necessary (see chapter FAQ). But if it's not too complicated, we implement the uninstall part for Chocolatey packages as it aids testing etc. (
chocolateyUninstall.ps1usually just calls
chocolateyInstall.ps1 -uninstallto keep all logic inside
- The second time that
Get-ChocolateyRealmjoinRegistryUninstallInfois used inside
chocolateyInstall.ps1of our standard packages only uninstalls newer or same versions of the software (
-versionGemeans versions greater or equal), as this is usually not being handled well by the installers themselves.
- In case of updating an older version of installed software, we expect this to be handled well by the installer itself. Therefore we do not do any uninstalls in this case (the vendor's installer might even contain logic to migrate settings etc. if it finds an older version already installed).
- If an uninstaller is unable to handle software updates properly,
chocolateyInstall.ps1will be customized to handle this itself (e.g. by always uninstalling any related software before installing).
- In case we should ever really need to uninstall a Chocolatey package (despite our first assumption), we usually build a craft package that more or less calls
choco to uninstall abc-xyz -y --skip-autouninstaller.
choco uninstallfrom within Chocolatey packages seems to work, but there is no guarantee here and we recommend to use craft packages for this purpose.