Summary

ISHRemote is a PowerShell module on SDL 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 SDL 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.

	Install-Module ISHRemote -Repository PSGallery -Scope CurrentUser -Force 

Update

Open a PowerShell and run.

    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.

Testing Known Issues

• If a test fails with Object reference not set to an instance of an object., it probably means that somewhere in your *.Tests.ps1 you return an object and forgot a Write-Host or something.

    Result StackTrace: 
    at PowerShellTools.TestAdapter.PowerShellTestExecutor.RunTest(PowerShell powerShell, TestCase testCase, IRunContext runContext)
    at PowerShellTools.TestAdapter.PowerShellTestExecutor.RunTests(IEnumerable``1 tests, IRunContext runContext, IFrameworkHandle frameworkHandle)
  

• When using Visual Studio to run a single "Run Selected Test", the Test Explorer in turn will run an Invoke-Pester command with the following parameters

  • Path The path where Invoke-Pester begins to search for test files. The default is the current directory.
  • TestName Informs Invoke-Pester to only run Describe blocks that match this name. This value may contain wildcards.
    This means that all *.Tests.ps1 are executed in the same folder back-to-back, but only the Describe that matches the given TestName will be trully tested. So every *.Tests.ps1 prerequisites and finally block will be called and have to be clean.

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

• Most Pester tests are acceptance test, enriched which some unit tests where possible.
• Using a dot-sourced ISHRemote.PesterSetup.ps1 include in all *.Tests.ps1 to specify the variables (not initialization) consistently
• Using the -Tag with "Create", "Read", "Update", "Delete" to allow [Pester grouping](See https://github.com/pester/Pester/wiki/Describe) Tags
• Data initialization and breakdown are key but also time consuming. BeforeEach/AfterEach are run for every It block, so makes things slow.

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 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.10-beta
7. Close version milestone on https://github.com/sdl/ISHRemote/milestone/

Testing and Debugging using Pester in Visual Studio 2015

src1 src2 src3 [src4](https://github.com/pester/Pester/wiki Prerequisites)

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

Prerequisites

1. Install or make sure you run Windows Management Framework v5, so Windows PowerShell v5 for Pester support, see https://msdn.microsoft.com/en-us/powershell/wmf/requirements

2. Install Powershell Tools for Visual Studio 2015

3. Install Pester and have it available in %userprofile%\My Documents\WindowsPowerShell\Modules\Pester

   Warning: Install Pester as Administrator, see : Install-Package Pester -Source PSGallery will eventually show you Failed to load Pester module. The specified module 'Pester' was not loaded because no valid module file was found in any module directory. when running Tests in Visual Studio Solution is to copy content of %ProgramFiles%\WindowsPowerShell\Modules\Pester\3.4.0" to "%userprofile%\My Documents\WindowsPowerShell\Modules\Pester

Debugging using F5 In Visual Studio 2015

src

In the properties window, select Debug tab and select Start external program under Start Options. Navigate to PowerShell.exe for the architecture of your project. In the Start Options -> Command Line Arguments textbox, enter the parameters for the PowerShell executable that will automatically load the module once it is compiled. The debugger starts always in the default location where the DLL is generated. So, there is no need to specify the full path. In the case of our module the option would be:

C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe
-noexit -command "&{ import-module .\ISHRemote.psm1 -verbose}"
OR
-noexit -command "&{ ..\..\Samples\Sample.Automate.EventMonitor.ps1}"
OR COMBINED
-noexit -command "&{ import-module .\ISHRemote.psm1 -verbose; ..\..\Samples\Sample.Automate.EventMonitor.ps1}"

Warning: If you get a security warning, run the above exact powershell.exe command using Run As Administrator, then execute Set-ExecutionPolicy Unrestricted

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

Static Code Analysis (experiment)

1. Using Docker Desktop and PowerShell Core 6 started docker run -d --name sonarqube -p 9000:9000 sonarqube
2. Navigated to http://localhost:9000/ going to through the new project wizard (admin, ISHRemote)
3. Using MSBuild Command Prompt for VS2015 triggered
   1. C:\TEMP\sonar\sonarscanner-msbuild\SonarScanner.MSBuild.exe begin /k:"ISHRemote" /d:sonar.host.url="http://localhost:9000" /d:sonar.login="9e96746fe7c2c8d11f6be0eed88cf3fb08c586d3"
   2. MsBuild.exe /t:Rebuild
   3. C:\TEMP\sonar\sonarscanner-msbuild\SonarScanner.MSBuild.exe end /d:sonar.login="9e96746fe7c2c8d11f6be0eed88cf3fb08c586d3"
4. Then look at the analysis :)