Libraries and Scripts

Last updated 2 months ago

Modules may contain PowerShell Script Library items and PowerShell Script items. The following section outlines some of the basic concepts you need to know for the following chapters.

PowerShell Script Library

The library items represent a collection of scripts, and may be structured with one or more levels of libraries.

Naming Convention

You'll find that with the Integration Points some libraries should be created with specific names (i.e. Content Editor, Control Panel).

As a best practice we recommend that the Functions library consist of reusable scripts containing PowerShell functions (i.e. Do-Something) while other libraries contain the solution specific scripts (i.e. MakeScriptingGreatAgain).

Example: The following demonstrates the use of the Functions script library containing Get-DateMessage.

# /sitecore/system/modules/powershell/script library/spe rocks/functions/get-datemessage
function Get-DateMessage {
"The current date and time is: $(Get-Date)"
}
# /sitecore/system/modules/powershell/script library/spe rocks/alerts/show-datemessage
Import-Function -Name Get-DateMessage
Show-Alert (Get-DateMessage)

Some names we've used included:

  • Beginner Tutorials

  • Content Editor

  • Content Maintenance

  • Content Interrogation

  • Development

  • Event Handlers

  • Functions

  • Internal

  • Page Editor

  • Pipelines

  • Profile and Security

  • Reports

  • Script Testing

  • Tasks

  • Toolbox

  • User Interaction

  • Web API

Note: Many of the of the libraries are integration points for the module. When the integration point wizard runs, you will see that these can be generated automatically.

Fields

Interactive : The following fields support the two custom rules as well as a variety of out-of-the-box rules.

  • ShowRule (Show if rules are met or not defined) - typically controls visibility of integration points.

    • PowerShell

      • where specific persistent PowerShell session was already initiated

      • where specific persistent PowerShell session was already initiated and has the specific variable defined and not null

      • where exposed in a specific view

    • PowerShell ISE

      • when length script length is compares to number characters long

      • when the edited script is in a state

  • EnableRule (Enable if rules are met or not defined) - typically controls enabled state of integration points.

    • Same as above

Rules Usage

There are a number of use cases for the EnableRule and ShowRule.

  • If there is a UI component the ShowRule can be used to ensure it appears while the EnableRule can toggle when it can be clicked.

  • If there is no UI component, the EnableRule is used to determine when the script should be executed; useful to limit creation of PowerShell runspaces.

ShowRule

EnableRule

Content Editor Context Menu

Content Editor Context Menu

Content Editor Gutter

Content Editor Insert Item

Content Editor Ribbon

Content Editor Ribbon

Content Editor Warning

DataSources

Event Handlers

ISE Plugin

ISE Plugin

Reports

Reports List View Action

Reports List View Action

Reports List View Export

Reports List View Export

Page Editor Notification

Page Editor Experience Button

Pipelines

Tasks

Toolbox

Workflow Action

PowerShell Script

The script items represent the code that will be executed.

Naming Convention

There are three conventions that we recommend you follow which are shown with an example below.

  • Title Casing - This should be used when the name will be exposed in places such as the Content Editor, script library names, and Reports root directory.

  • Sentence casing - This should be used when the name is long and will not be visible to the user or is a report with a very long name.

  • Noun-Verb - This should be used when the script is stored within the Functions script library and will be imported using the command Import-Function.

Fields

Interactive : Refer to the description shown for PowerShell Script Library fields.

Scripting

  • Script (Script body) : This is a multi-line text than should be edited using the PowerShell ISE application.

Session Persistency

  • PersistentSessionId (Persistent Session ID) : Context scripts using this ID will execute in a single session and be reused; leaving empty will cause the session to be discarded after execution. This value should be used for rules requesting the session ID.