Issue-413 - Add ReturnJson parameter (#419)

PlagueHO · May 23, 2021 · 98fd6e4 · 98fd6e4
1 parent 8b20ce4
commit 98fd6e4
Show file tree

Hide file tree

Showing 11 changed files with 448 additions and 38 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,6 +18,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Fix CI pipeline deployment stage to ensure correctly detects running
   in Azure DevOps organization.
+- Fix CI pipeline release stage by adding Sampler GitHub tasks which
+  were moved out of the main sampler module into a new module
+  `Sampler.GitHubTasks` - Fixes [Issue #418](https://github.com/PlagueHO/CosmosDB/issues/418).
+
+### Added
+
+- Added `ReturnJson` parameter to `New-CosmosDbDocument`, `Set-CosmosDbDocument`
+  and `Get-CosmosDbDocument` functions to allow return of documents that can
+  not be converted to objects due to duplicate key names that only differ in
+  case - Fixes [Issue #413](https://github.com/PlagueHO/CosmosDB/issues/413).
 
 ## [4.4.3] - 2020-11-13
 

diff --git a/RequiredModules.psd1 b/RequiredModules.psd1
@@ -1,20 +1,21 @@
 @{
-    PSDependOptions     = @{
+    PSDependOptions       = @{
         AddToPath  = $true
         Target     = 'output\RequiredModules'
         Parameters = @{
             Repository = ''
         }
     }
-    invokeBuild         = 'latest'
-    PSScriptAnalyzer    = 'latest'
-    Pester              = '4.10.1'
-    Plaster             = 'latest'
-    Platyps             = 'latest'
-    ModuleBuilder       = 'latest'
-    ChangelogManagement = 'latest'
-    Sampler             = 'latest'
-    MarkdownLinkCheck   = 'latest'
-    'Az.Accounts'       = '1.5.1'
-    'Az.Resources'      = '1.3.1'
+    invokeBuild           = 'latest'
+    PSScriptAnalyzer      = 'latest'
+    Pester                = '4.10.1'
+    Plaster               = 'latest'
+    Platyps               = 'latest'
+    ModuleBuilder         = 'latest'
+    ChangelogManagement   = 'latest'
+    Sampler               = 'latest'
+    'Sampler.GitHubTasks' = 'latest'
+    MarkdownLinkCheck     = 'latest'
+    'Az.Accounts'         = '1.5.1'
+    'Az.Resources'        = '1.3.1'
 }
diff --git a/build.yaml b/build.yaml
@@ -95,8 +95,8 @@ BuildWorkflow:
     - Pester_if_Code_Coverage_Under_Threshold
 
   publish:
-    - Publish_release_to_GitHub
-    - publish_module_to_gallery
+    - Publish_Release_To_GitHub
+    - Publish_Module_To_gallery
 
 
 ####################################################
@@ -121,6 +121,8 @@ Resolve-Dependency:
 ModuleBuildTasks:
   Sampler:
     - '*.build.Sampler.ib.tasks'
+  Sampler.GitHubTasks:
+    - '*.ib.tasks'
 
 TaskHeader: |
   param($Path)

diff --git a/docs/Get-CosmosDbDocument.md b/docs/Get-CosmosDbDocument.md
@@ -21,7 +21,8 @@ Get-CosmosDbDocument -Context <Context> [-Key <SecureString>] [-KeyType <String>
  [-PartitionKey <Object[]>] [-MaxItemCount <Int32>] [-ContinuationToken <String>]
  [-ConsistencyLevel <String>] [-SessionToken <String>]
  [-PartitionKeyRangeId <String>] [-Query <String>] [-QueryParameters <Hashtable[]>]
- [-QueryEnableCrossPartition <Boolean>] [-ResponseHeader <PSReference>] [<CommonParameters>]
+ [-QueryEnableCrossPartition <Boolean>] [-ResponseHeader <PSReference>]
+ [-RetrunJson <switch>] [<CommonParameters>]
 ```
 
 ### Account
@@ -32,7 +33,8 @@ Get-CosmosDbDocument -Account <String> [-Key <SecureString>] [-KeyType <String>]
  [-PartitionKey <Object[]>] [-MaxItemCount <Int32>] [-ContinuationToken <String>]
  [-ConsistencyLevel <String>] [-SessionToken <String>]
  [-PartitionKeyRangeId <String>] [-Query <String>] [-QueryParameters <Hashtable[]>]
- [-QueryEnableCrossPartition <Boolean>] [-ResponseHeader <PSReference>] [<CommonParameters>]
+ [-QueryEnableCrossPartition <Boolean>] [-ResponseHeader <PSReference>]
+ [-RetrunJson <switch>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -96,6 +98,16 @@ PS C:\> Get-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewColle
 
 Query the documents in a collection using a parameterized query.
 
+### Example 6
+
+```powershell
+PS C:\> Get-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id 'ac12345' -ReturnJson
+```
+
+Return a document with a Id 'ac12345' from a collection in the database as
+JSON string rather than an object. This is useful if the document returned
+contain duplicate keys that differing only in case.
+
 ## PARAMETERS
 
 ### -Account
@@ -391,6 +403,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ReturnJson
+
+Prevents the information returned by Cosmos DB from the request to be converted
+into an object. This switch is required if the document being added to Cosmos DB
+has key names that are duplicates, differing only in case.
+
+```yaml
+Type: switch
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/New-CosmosDbDocument.md b/docs/New-CosmosDbDocument.md
@@ -19,7 +19,7 @@ Create a new document for a collection in a Cosmos DB database.
 New-CosmosDbDocument -Context <Context> [-KeyType <String>] [-Key <SecureString>]
  [-Database <String>] -CollectionId <String> -DocumentBody <String>
  [-IndexingDirective <String>] [-Upsert <Boolean>] [-PartitionKey <Object[]>]
- [-Encoding <String>] [<CommonParameters>]
+ [-Encoding <String>] [-RetrunJson <switch>] [<CommonParameters>]
 ```
 
 ### Account
@@ -28,7 +28,7 @@ New-CosmosDbDocument -Context <Context> [-KeyType <String>] [-Key <SecureString>
 New-CosmosDbDocument -Account <String> [-KeyType <String>] [-Key <SecureString>]
  [-Database <String>] -CollectionId <String> -DocumentBody <String>
  [-IndexingDirective <String>] [-Upsert <Boolean>] [-PartitionKey <Object[]>]
- [-Encoding <String>] [<CommonParameters>]
+ [-Encoding <String>] [-RetrunJson <switch>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -82,6 +82,25 @@ PS C:\> New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'Partitione
 Create a new document containing UTF-8 encoded strings in a non-partitioned collection
 in a database.
 
+### Example 4
+
+```powershell
+PS C:\> $document = @"
+{
+    `"id`": `"en-us`",
+    `"content`": {
+        `"key`": `"lower case key`",
+        `"KEY`": `"upper case key`"
+    }
+}
+"@
+PS C:\> New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'PartitionedCollection' -DocumentBody $document -ReturnJson
+```
+
+Create a new document containing a document with JSON that can not be returned as
+an object due to keys that differ only in case. This will return
+the output as JSON.
+
 ## PARAMETERS
 
 ### -Account
@@ -278,6 +297,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ReturnJson
+
+Prevents the information returned by Cosmos DB from the request to be converted
+into an object. This switch is required if the document being added to Cosmos DB
+has key names that are duplicates, differing only in case.
+
+```yaml
+Type: switch
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/docs/Set-CosmosDbDocument.md b/docs/Set-CosmosDbDocument.md
@@ -18,7 +18,8 @@ Update a document from a Cosmos DB collection.
 ```powershell
 Set-CosmosDbDocument -Context <Context> [-Database <String>] [-Key <SecureString>]
  -CollectionId <String> -Id <String> -DocumentBody <String> [-IndexingDirective <String>]
- [-PartitionKey <Object[]>] [-Encoding <String>] [-ETag <String>] [<CommonParameters>]
+ [-PartitionKey <Object[]>] [-Encoding <String>] [-ETag <String>]
+ [-RetrunJson <switch>] [<CommonParameters>]
 ```
 
 ### Account
@@ -27,7 +28,7 @@ Set-CosmosDbDocument -Context <Context> [-Database <String>] [-Key <SecureString
 Set-CosmosDbDocument -Account <String> [-Database <String>] [-Key <SecureString>]
  [-KeyType <String>] -CollectionId <String> -Id <String> -DocumentBody <String>
  [-IndexingDirective <String>] [-PartitionKey <Object[]>] [-Encoding <String>]
- [-ETag <String>] [<CommonParameters>]
+ [-ETag <String>] [-RetrunJson <switch>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -83,6 +84,25 @@ Increment the counter of a document. Make sure that the document has not been
 modified between get and set operations by supplying the ETag from the original
 document.
 
+### Example 4
+
+```powershell
+PS C:\> $newDocument = @"
+{
+    `"id`": `"ac12345`",
+    `"content`": {
+        `"key`": `"lower case key`",
+        `"KEY`": `"upper case key`"
+    }
+}
+"@
+PS C:\> Set-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id 'ac12345' -DocumentBody $newDocument
+```
+
+Replace an existing document containing a document with JSON that can not be
+returned as an object due to keys that differ only in case. This will return
+the output as JSON.
+
 ## PARAMETERS
 
 ### -Account
@@ -291,6 +311,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ReturnJson
+
+Prevents the information returned by Cosmos DB from the request to be converted
+into an object. This switch is required if the document being added to Cosmos DB
+has key names that are duplicates, differing only in case.
+
+```yaml
+Type: switch
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

diff --git a/source/Public/documents/Get-CosmosDbDocument.ps1 b/source/Public/documents/Get-CosmosDbDocument.ps1
@@ -89,20 +89,40 @@ function Get-CosmosDbDocument
         [Alias("ResultHeaders")]
         [Parameter()]
         [ref]
-        $ResponseHeader
+        $ResponseHeader,
+
+        [Parameter()]
+        [switch]
+        $ReturnJson
     )
 
-    $documentJson = Get-CosmosDbDocumentJson @PSBoundParameters
+    $null = $PSBoundParameters.Remove('ReturnJson')
 
-    $documents = ConvertFrom-Json -InputObject $documentJson
+    $documentJson = Get-CosmosDbDocumentJson @PSBoundParameters
 
-    if ([System.String]::IsNullOrEmpty($Id))
+    if ($ReturnJson.IsPresent)
     {
-        $documents = $documents.Documents
+        return $documentJson
     }
-
-    if ($documents)
+    else
     {
-        return (Set-CosmosDbDocumentType -Document $documents)
+        try
+        {
+            $documents = ConvertFrom-Json -InputObject $documentJson
+
+            if ([System.String]::IsNullOrEmpty($Id))
+            {
+                $documents = $documents.Documents
+            }
+
+            if ($documents)
+            {
+                return (Set-CosmosDbDocumentType -Document $documents)
+            }
+        }
+        catch
+        {
+            New-CosmosDbInvalidOperationException -Message ($LocalizedData.ErrorConvertingDocumentJsonToObject)
+        }
     }
 }
diff --git a/source/Public/documents/New-CosmosDbDocument.ps1 b/source/Public/documents/New-CosmosDbDocument.ps1
@@ -58,12 +58,17 @@ function New-CosmosDbDocument
         [Parameter()]
         [ValidateSet('Default', 'UTF-8')]
         [System.String]
-        $Encoding = 'Default'
+        $Encoding = 'Default',
+
+        [Parameter()]
+        [switch]
+        $ReturnJson
     )
 
     $null = $PSBoundParameters.Remove('CollectionId')
     $null = $PSBoundParameters.Remove('Id')
     $null = $PSBoundParameters.Remove('DocumentBody')
+    $null = $PSBoundParameters.Remove('ReturnJson')
 
     $resourcePath = ('colls/{0}/docs' -f $CollectionId)
 
@@ -100,10 +105,24 @@ function New-CosmosDbDocument
         -Body $DocumentBody `
         -Headers $headers
 
-    $document = ConvertFrom-Json -InputObject $result.Content
-
-    if ($document)
+    if ($ReturnJson.IsPresent)
+    {
+        return $result.Content
+    }
+    else
     {
-        return (Set-CosmosDbDocumentType -Document $document)
+        try
+        {
+            $document = ConvertFrom-Json -InputObject $result.Content
+        }
+        catch
+        {
+            New-CosmosDbInvalidOperationException -Message ($LocalizedData.ErrorConvertingDocumentJsonToObject)
+        }
+
+        if ($document)
+        {
+            return (Set-CosmosDbDocumentType -Document $document)
+        }
     }
 }