Unregister-PackageSource -Name CiresonPublicFeed
Platform Powershell Management
Synopsis
This document will delve into managing the Cireson Platform from Powershell. Powershell allows you a great deal of flexibility in installing, and managing Cireson applications that run on top of the Cireson Platform.
Installation
Installation of the Cireson Platform is done by the use of either the GUI Setup application, or the CpexLets Cmdlet module.
In this article, I will be going over some basics of Platform installation, and demonstrating how to install the platform into your environment using the previously mentioned PowerShell module.
Installation of the Platform itself is a rather simple operation, one simply needs to copy the appropriate binaries into a directory on the local server, and execute Cireson.Platform.Host.exe with appropriate command line arguments. A list of available arguments can be found by executing Cireson.Platform.Host.exe /? from a command line.
The CpexLets powershell module provides a number of handy commands that allow you to install the platform, create and save specific configurations, install applications to your running platform and uninstall the platform.
In order to follow along with this guide, you should have a computer that meets the minimum requirements for running the Cireson Platform, including SQLServer.
Installing Cireson Cpexlets Powershell Module
The first step to be able to install the Cireson Platform is to retrieve the CpexLets module. To do this we need to first register the Cireson Package feed, then we can import the CpexLets module, and start running commands.
- Open a Powershell command window as administrator
- Execute the following PowerShell command
Register-PackageSource "https://pkgs.dev.azure.com/Cireson/Public/_packaging/dev/nuget/v2" -Name dev -Trusted -ProviderName PowerShellGet
- This will add the Cireson Development Package Feed to your list of trusted package feeds. If you later wish to unregister the feed, you can do so by executing the following command
Unregister-PackageSource -Name dev
Next we need to import the CpexLets module. Execute the following command (Note: new dev.azure.com feeds require Cpexlets >= 2.0.0)
Install-Module -Name CpexLets -force
Use "Uninstall-Module -Name CpexLets -AllVersions -force" to remove Cpexlets from your computer
You can Install again later.
Now we are ready to start using the CpexLets to manage our Platform.
Setting the correct feed source
- From the powershell prompt, execute the following command to connect to the Development feed
Connect-CPEXFeed -feedName dev
- This will ensure that commands are routed to the appropriate nuget feed.
Finding Applications to install
By itself, the Cireson Platform represents an extensible runtime that provides OData services, Scheduled Task, and Worker management. In order to do anything useful, you typically need to install one or more Cpex Applications. A Cpex Application is a regular Cpex that represents everything needed to run the application on the Cireson Platform. Most applications will reference one or more additional Cpex extensions.
- You can list the applications that are available on the connected feed using the following command
Get-CPEXApplications
- You should see a list of Applications that are available for the current feed.
Creating a PlatformConfig for installation
A Platform Config allows you to define various parameters that you can use to install the platform, you can save the configuration, and use it later. During installation depending on the context of the installation, you can alter discreet properties specific to the current installation.
- From your Powershell window, execute the following command replacing values for sqlServerName, databaseName, productKey, and configFilePath to match your environment:
Get-CPEXPlatformConnectionString -sqlServerName localhost -databaseName CiresonPlatformTutorial | New-CPEXPlatformConfig -ServiceName CiresonTutorial -installPath c:\CiresonPlatformTutorial\platform -productKey 123123123 -defaultApplicationName Cireson.AssetManagement.SAM -configFilePath c:\CiresonPlatformTutorial\PlatformTutorial.config
- Look at the file that was generated in configFilePath so you can see what the configuration values look like.
- There are additional options available when creating a new PlatformConfig file. You can use New-CPEXPlatformConfig -? to get more information on the specific parameters and their usage.
Installing a Cireson Platform Application from Powershell
In order to install a platform application, we simply need to get the PlatformConfig that we created in the previous step, and pipe it into the Install-CpexPlatform cmdlet.
- From Powershell execute the following command, replacing the file path with the path you chose in the previous step, and adding a local or domain service user
Get-CPEXPlatformConfig -path C:\CiresonPlatformTutorial\PlatformTutorial.config | Install-CPEXPlatform -serviceUser .\test -servicePassword P@ssW0rd
- In a moment, you will see the results of the command in the console.
- Open a web browser (I recommend Chrome as it allows you to view Json in the page, and has some nice extensions to prettify it)
- Navigate to http://localhost/api you should see the default oData endpoint
- In the background, the platform is installing the SAM extension. Once installed the platform will restart, and you will see a Platform Starting message if you refresh the page
- When the platform comes back up, navigate to http://localhost and you will be presented with the Cireson.AssetManagement.SAM default UI.
Uninstalling the platform service
Uninstalling the platform service will remove the service from the Service Control Manager, but will not remove the database, or the local files.
- To uninstall the platform that we just installed, run the following command
Get-CPEXPlatformConfig -path C:\CiresonPlatformTutorial\PlatformTutorial.config | Uninstall-CPEXPlatform
Installing a CPEX Package to a running Cireson Platform
Installing a CPEX package is fairly straight forward. Simply identify the name of the CPEX Package you wish to install, and execute the Install-CPEXApplication
command.
example:
Install-CPEXApplication -applicationId Cireson.PasswordReset
Note
Specify additional parameters for credential and platformUrl if you are not running locally.
CPEXLets Command List
to view a full list of available commands, execute the following Powershell command:
Get-Command -Module CpexLets
Getting additional help
All exported functions in the Powershel Module are prefixed with {verb}-CPEX{Command} To get help for a specific command, type the command followed by -? ex:
Invoke-CPEXPlatformApiCommand -?
Returns:
NAME
Invoke-CPEXPlatformApiCommand
SYNOPSIS
Invokes an http REST command against the platformRootUri
SYNTAX
Invoke-CPEXPlatformApiCommand [[-method] <String>] [[-body] <Object>] [[-platformRootUri] <String>] [[-command] <String>] [[-apiToken] <String>] [[-credential] <PSCredential>] [<CommonParameters>]