#123 Parameter -RequestedMetadata added similar Search-IshDocumentObj…

… allowing to skip an additional Get-IshDocumentObj call which slows things down on bigger legacy data sets. Now with tweaked examples, and Pester tests.

Doc/ReleaseNotes-ISHRemote-0.13.md

@@ -62,17 +62,18 @@ The alternative is to navigate your data set in smaller chunks, then folders com
 1. Base folder `Data` is in practice "General", the repository root folder. Parameter `-FolderTypeFilter` is explicitly set for all content objects, implicitly skipping ISHPublication. Ommitting `-FolderTypeFilter` in practice means no filtering on object type.
 1. The pipeline IshFolder objects are passed to `Foreach-Object {...}` (short hand `%{...}`) to create a script block for custom actions.
     1. The pipeline IshFolder object in the script block is available as `$PSItem` (short hand `$_`). Initially to print a folder name.
-    1. The pipeline IshFolder object is passed to retrieve its folder content, specifically all languages on the latest (highest) version.
+    1. The pipeline IshFolder object is passed to retrieve its folder content, specifically all languages on the latest (highest) version. The `-RequestedMetadata` parameter allows to retrieve extra metadata on top of the IshSession `DefaultRequestedMetadata` (since [#123](https://github.com/sdl/ISHRemote/issues/123)).
     1. Returned IshObjects can be further handled like `Set-IshDocumentObj` or write to file, or `Get-IshDocumentObjData` to retrieve the actual files.
 1. Optionally in this sample, the pipeline IshObjects are passed to `Out-GridView` for visual representation. Notice the `-PassThru` which allows even further selection in that grid view, after pressing OK the selection is passed to the pipeline again.
 
 ```powershell
 New-IshSession -WsBaseUrl https://example.com/ISHWS/ -PSCredential Admin
 $metadataFilter = Set-IshMetadataFilterField -Level Lng -Name CHECKED-OUT-BY -FilterOperator In -Value ("Admin, Admin2")
+$requestedMetadata = Set-IshRequestedMetadataField -Level Lng -Name FISHSTATUSTYPE
 $ishObjects = Get-IshFolder -BaseFolder Data -FolderTypeFilter @("ISHModule", "ISHMasterDoc", "ISHLibrary", "ISHIllustration", "ISHTemplate")  -Recurse | 
 Foreach-Object {
     Write-Host ("Handling folder[$($PSItem.name)]...")
-    $ishObjects = Get-IshFolderContent -IshFolder $PSItem -VersionFilter Latest -MetadataFilter $metadataFilter
+    $ishObjects = Get-IshFolderContent -IshFolder $PSItem -VersionFilter Latest -MetadataFilter $metadataFilter -RequestedMetadata $requestedMetadata
     # Create some report, some extra checks, a transformation, etc
     Write-Output $ishObjects
 } |

Source/ISHRemote/Trisoft.ISHRemote/Cmdlets/Folder/GetIshFolderContent.Tests.ps1

@@ -38,7 +38,8 @@ Describe “Get-IshFolderContent" -Tags "Read" {
 	}
 
 	Context "Get-IshFolderContent returns latest IshObject[] object" {
-		$ishObjects = Get-IshFolderContent -IShSession $ishSession -IshFolder $ishFolderTopic
+		$requestedMetadata = Set-IshRequestedMetadataField -Level Lng -Name FISHSTATUSTYPE
+		$ishObjects = Get-IshFolderContent -IShSession $ishSession -IshFolder $ishFolderTopic -RequestedMetadata $requestedMetadata
 		It "GetType().Name" {
 			$ishObjects.GetType().Name | Should BeExactly "Object[]"
 		}
@@ -83,12 +84,14 @@ Describe “Get-IshFolderContent" -Tags "Read" {
 			$ishObjects[0].version_version_value -ge 2 | Should Be $true 
 			#language
 			$ishObjects[0].fstatus.Length -ge 1 | Should Be $true 
-			$ishObjects[0].fstatus_lng_element.StartsWith('VSTATUS') | Should Be $true 
+			$ishObjects[0].fstatus_lng_element.StartsWith('VSTATUS') | Should Be $true
+			$ishObjects[0].fishstatustype -ge 0 | Should Be $true
 		}
 	}
 
 	Context "Get-IshFolderContent with empty VersionFilter returns IshObject[] object" {
-		$ishObjects = Get-IshFolderContent -IShSession $ishSession -VersionFilter "" -IshFolder $ishFolderTopic
+		$requestedMetadata = Set-IshRequestedMetadataField -Level Lng -Name FISHSTATUSTYPE
+		$ishObjects = Get-IshFolderContent -IShSession $ishSession -VersionFilter "" -IshFolder $ishFolderTopic -RequestedMetadata $requestedMetadata
 		It "GetType().Name" {
 			$ishObjects.GetType().Name | Should BeExactly "Object[]"
 		}
@@ -134,6 +137,7 @@ Describe “Get-IshFolderContent" -Tags "Read" {
 			#language
 			$ishObjects[0].fstatus.Length -ge 1 | Should Be $true 
 			$ishObjects[0].fstatus_lng_element.StartsWith('VSTATUS') | Should Be $true 
+			$ishObjects[0].fishstatustype -ge 0 | Should Be $true
         }
         It "ishObjects[0].version_version_value" { 
             # First version

Source/ISHRemote/Trisoft.ISHRemote/Cmdlets/Folder/GetIshFolderContent.cs

@@ -74,6 +74,7 @@ namespace Trisoft.ISHRemote.Cmdlets.Folder
     /// Get-IshFolderContent -VersionFilter "" -MetadataFilter $metadataFilter -RequestedMetadata $requestedMetadata 
     /// </code>
     /// <para>New-IshSession will submit into SessionState, so it can be reused by this cmdlet. The metadata filter will filter out source languages and the empty VersionFilter will return all versions of any object. The recursive folder allows you to control which area you do a check/conversion in, and give you progress as well.</para>
+    /// <para>Note that -RequestedMetadata will be used on every folder passed over the pipeline by Get-IshFolder. Requesting metadata for Topics (ISHModule) might be unexisting on Publication folders or vice versa. Know that Get-IshFolder has a -FolderTypeFilter parameter to workaround that.</para>
     /// </example>
     /// <example>
     /// <code>