Summary

ISHRemote is a PowerShell module on Tridion Docs Content Manager. Its goal is business automation on top of the Component Content Management System (Knowledge Center Content Manager, LiveContent Architect, Trisoft InfoShare). This library is constructed close to the "Web Services API" to:

• allow business logic automation ranging from triggering publishing into the continuous integration pipeline over legacy data correction up to provisioning
• show case code examples and API best practices

Videos

Have a look at the Automating tasks in Tridion Docs using PowerShell webinar. Supporting material, so you can easily copy-paste is on

• Webinar Blogpost - Getting started with Microsoft PowerShell
• Webinar Blogpost - Examples

Features & Samples

• This library is a relatively thin client layer on top of the business API.
• -WhatIf/-Confirm are implemented on write operations.
• Add-* cmdlets will immediately create objects in the CMS, and return you an in-memory result holding basic identifiers ($ishSession.DefaultRequestedMetadata) to continue the pipeline.
• Remove-* cmdlets will not return any in-memory result.
• Set-*, Move-*, Publish-* and Stop-* cmdlets will immediately update existing objects in the CMS, and return you an in-memory result holding descriptive identifiers to continue the pipeline. You cannot use Set-* for creation.
• New-* cmdlets will create in-memory objects to locally update and then potentially pass to Add-* andSet-* cmdlets.
• Get-* and Find-* cmdlets return existing objects present in the CMS, and return you an in-memory result holding descriptive identifiers to continue the pipeline.
  • The Find- cmdlets was built on top of the API Find operation, which triggers a query to find all objects matching the filter criteria.
  • The Get- cmdlets was built on top of the API Retrieve/Get operations, which trigger a query given object identifiers and then potentially extra filter criteria.
• Supports ISHIntegrationSTSInternalAuthentication as implemented by ISHDeploy.

Install & Update

Prerequisites

When you have Windows PowerShell 5 on your client machine, the PSVersion entry in $PSVersionTable reads 5.0... and PackageManagement is there implicitly. When you have a Windows PowerShell version lower than 5 on your client machine, the PSVersion entry in $PSVersionTable reads 4.0 or even 3.0. Note that the latest Knowledge Center 2016SP4/12.0.4 release is only verified with Windows PowerShell 4, so don't upgrade your servers. While Tridion Docs 13/13.0.0 is verified for Windows PowerShell 5.

So we prefer you to upgrade to Windows Management Framework 5.0.

Note that we rely on Windows PowerShell (FullCLR), and not PowerShell Core (CoreCLR) which relies on .NET Core. Main reason is that the Core edition doesn't offer all supporting libraries for WS-Trust based authentication like System.IdentityModel and System.ServiceModel.

Install

Open a PowerShell, then you can find and install the ISHRemote module. CurrentUser -Scope indicates that you don't have to run PowerShell as Administrator. The -Force will make you bypass some security/trust questions.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12  # as PSGallery switched to HTTPS over Tls12 and higher
Install-Module ISHRemote -Repository PSGallery -Scope CurrentUser -Force 

Update

Open a PowerShell and run.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12  # as PSGallery switched to HTTPS over Tls12 and higher
Update-Module ISHRemote

Uninstall

Open a PowerShell and run.

Uninstall-Module ISHRemote -AllVersion 

Backlog & Feedback

Any feedback is welcome. Please log a GitHub issue, make sure you submit your version number, expected and current result,...

Backlog

Known Issues & FAQ

Execution Known Issues

• If you get New-IshSession : Reference to undeclared entity 'raquo'. Line 98, position 121., most likely you specified an unexisting "Web Services API" url. Make sure your url ends with an ending slash /.
• If a test fails with The communication object, System.ServiceModel.Channels.ServiceChannel, cannot be used for communication because it is in the Faulted state., it probably means you didn't provide enough (mandatory) parameters to the WCF/SVC code so passing null parameters. Typically an -IshPassword is missing or using an existing username.
• ISHDeploy Enable-ISHIntegrationSTSInternalAuthentication/Disable-ISHIntegrationSTSInternalAuthentication adds a /ISHWS/Internal/connectionconfiguration.xml that a different issuer should be used. As ISHRemote doesn't have an app.config, all the artifacts are derived from the RelyingParty WSDL provided mex endpoint (e.g. /ISHSTS/issue/wstrust/mex).
  If you get error New-IshSession : The communication object, System.ServiceModel.Channels.ServiceChannel, cannot be used for communication because it is in the Faulted state., it probably means you initialized -WsBaseUrl without the /Internal/ (or /SDL/) segment, meaning you are using the primary configured STS.

Documentation Known Issues

• XmlDoc2CmdletDoc bug 22 System.ArgumentException: Property Get method was not found. at XmlDoc2CmdletDoc.Core.Domain.Parameter.get_DefaultValue() means you are missing a Get'er on a Property like public IshFolder IshFolder { set { _folderId = value.IshFolderRef; } }
• XmlDoc2CmdletDoc bug 23 System.NullReferenceException: Object reference not set to an instance of an object. at XmlDoc2CmdletDoc.Core.Domain.Command.<>c.<get_OutputTypes> Retrieve-IshFolder had [OutputType(nameof(IshFolder))], which should have been [OutputType(typeof(IshFolder))].

Standards To Respect

Coding Standards

• Any code change should
  • respect the coding standard like Strongly Encouraged Development Guidelines and Windows PowerShell Cmdlet Concepts
  • come with matching acceptance/unit test, to further improve stability and predictability
  • come with matching tripple-slash /// documentation verification or adaptation. Remember Get-Help drives PowerShell!
  • double check backward compatibility; if you break provide an alternative through Set-Alias, Get-Help,...
  • Any url reference should be specified with ...example.com in samples and Service References.
• Respect PowerShell concepts
  • parameters are Single not plural, so IshObject over IshObjects or FilePath over FilePaths
  • implement -WhatIf/-Confirm flags for write operations
• ISHRemote-build project holds the artefacts for in-house testing, signing, and publishing the library

Documentation Standards

• Inline *.cs tripple-slash /// documentation. Syntax options are explained on simple-talk.com. XmlDoc2CmdletDoc generates the requisite MAML file for you using essentially standard C# doc-comments embedded directly in your code, just like documenting any other C# library. Now you can document PowerShell simply and easily, and keep it synchronized with the code.
• Document the container object class like IshSession, and not the using parameters like -IshSession everywhere.

XmlDoc2CmdletDoc

Inline *.cs tripple-slash /// documentation. Syntax options are explained on simple-talk.com. XmlDoc2CmdletDoc generates the requisite MAML file for you using essentially standard C# doc-comments embedded directly in your code, just like documenting any other C# library. Now you can document PowerShell simply and easily, and keep it synchronized with the code.

Testing Standards

Initial testing was based on Pester 3.4.0 which came as part of Windows 10/2016, to introduce support for PowerShell 7+ we switched to Pester 5+ (#115|#132). To force an upgrade from pre-packaged Pester 3.4.0, have a look at Pester Installation, although on most systems it comes down to Install-Module -Name Pester -Force -SkipPublisherCheck.

• Most Pester tests are acceptance test, enriched which some unit tests where possible.
• Using a central ISHRemote.PesterSetup.ps1 (with optional ISHRemote.PesterSetup.Debug.ps1 override) in all *.Tests.ps1 to specify the variables (not initialization) consistently
• Data initialization and breakdown are key but also time consuming. After a test run, your system is left in its original state.

In ISHRemote.PesterSetup.Debug.ps1 override the global variables used for tests. Don't forget not to commit those custom values.

Coding Prerequisites and Best Practices

Release Build and Publish To PowerShell Gallery

Rought steps to release...

1. Use Visual Studio to build a Debug build. Run an Invoke-Pester (minimally v5.3.0) on C:\GITHUB\ishremote\Source\ISHRemote\Trisoft.ISHRemote. All steps should be green.
2. Use Visual Studio to build a Release build. Change C:\GITHUB\ISHRemote\Source\ISHRemote\Trisoft.ISHRemote\ISHRemote.PesterSetup.ps1 to forcefully load \bin\release\ (instead of \bin\debug\). Run an Invoke-Pester on C:\GITHUB\ishremote\Source\ISHRemote\Trisoft.ISHRemote. All steps should be green.
3. The folder content of C:\GITHUB\ISHRemote\Source\ISHRemote\Trisoft.ISHRemote\bin\Release\ will be published
   1. Check all files, especially Scripts that you have all files.
   2. Check version number of ISHRemote.dll
4. Execute steps regarding signing and publishing from SignAndPublish.ps1 available on internal repository https://stash.sdl.com/users/ddemeyer/repos/ishremote-build/
5. Check availability of latest version on https://www.powershellgallery.com/packages/ISHRemote/
6. Github releases
   1. Edit and release the notes on https://github.com/sdl/ISHRemote/releases/
   2. Start new release notes, under a new version number like v0.14-beta
7. Close version milestone on https://github.com/sdl/ISHRemote/milestone/

Debugging PowerShell in Visual Studio Code

Setting up your Visual Studio Code is explained on the internet, see Scripting Guys who in turn link to

• Get started with PowerShell development in Visual Studio Code
• Visual Studio Code editing features for PowerShell development – Part 1
• Visual Studio Code editing features for PowerShell development – Part 2
• Debugging PowerShell script in Visual Studio Code – Part 1
• Debugging PowerShell script in Visual Studio Code – Part 2
• Tyler Leonhardt - Visual Studio Code: deep dive into debugging your PowerShell scripts
• Writing Compiled PowerShell Cmdlets by Thomas Rayner