Merge pull request #195 from PlagueHO/Issue-151

Added support for creating UTF-8 Documents - Fixes #151

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## Unreleased
+
+- Added support for creating and updating documents containing
+  non-ASCII characters by adding Encoding parameter to `New-CosmosDbDocument`
+  and `Set-CosmosDbDocument` functions - fixes [Issue #151](https://github.com/PlagueHO/CosmosDB/issues/151).
+- Fix table of contents link in README.MD.
+
 ## 2.1.9.92
 
 - Improved unit test reliability on MacOS and Linux.

README.md

@@ -42,7 +42,7 @@
     - [Create a Context specifying the Key Manually](#create-a-context-specifying-the-key-manually)
     - [Use CosmosDB Module to Retrieve Key from Azure Management Portal](#use-cosmosdb-module-to-retrieve-key-from-azure-management-portal)
     - [Create a Context for a Cosmos DB Emulator](#create-a-context-for-a-cosmos-db-emulator)
-    - [Create a Context from Resource Authorization Tokens](#create-a-Context-from-resource-authorization-tokens)
+    - [Create a Context from Resource Authorization Tokens](#create-a-context-from-resource-authorization-tokens)
   - [Working with Accounts](#working-with-accounts)
   - [Working with Databases](#working-with-databases)
   - [Working with Offers](#working-with-offers)
@@ -357,6 +357,20 @@ New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -
 }
 ```
 
+Create a new document containing non-ASCII characters in a collection in the
+database:
+
+```powershell
+$document = @"
+{
+    `"id`": `"$([Guid]::NewGuid().ToString())`",
+    `"content`": `"杉本 司`"
+}
+"@
+New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentBody $document -Encoding 'UTF-8'
+}
+```
+
 Get the first 5 documents from the collection in the database:
 
 ```powershell

docs/Invoke-CosmosDbRequest.md

@@ -18,15 +18,15 @@ Execute a new request to a Cosmos DB REST endpoint.
 ```powershell
 Invoke-CosmosDbRequest -Context <Context> [-Database <String>] [-Key <SecureString>] [-KeyType <String>]
  [-Method <String>] -ResourceType <String> [-ResourcePath <String>] [-Body <String>] [-ApiVersion <String>]
- [-Headers <Hashtable>] [-ContentType <String>] [<CommonParameters>]
+ [-Headers <Hashtable>] [-ContentType <String>] [-Encoding <String>] [<CommonParameters>]
 ```
 
 ### Account
 
 ```powershell
 Invoke-CosmosDbRequest -Account <String> [-Database <String>] [-Key <SecureString>] [-KeyType <String>]
  [-Method <String>] -ResourceType <String> [-ResourcePath <String>] [-Body <String>] [-ApiVersion <String>]
- [-Headers <Hashtable>] [-ContentType <String>] [<CommonParameters>]
+ [-Headers <Hashtable>] [-ContentType <String>] [-Encoding <String>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -260,6 +260,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Encoding
+
+This parameter allows the Encoding to be set in the ContentType of the
+request to allow other encoding formats. Currently only UTF-8 is supported.
+If this parameter is not specified the default encoding is used.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+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.

docs/New-CosmosDbDocument.md

@@ -18,15 +18,15 @@ Create a new document for a collection in a Cosmos DB database.
 ```powershell
 New-CosmosDbDocument -Context <Context> [-KeyType <String>] [-Key <SecureString>] [-Database <String>]
  -CollectionId <String> -DocumentBody <String> [-IndexingDirective <String>] [-Upsert <Boolean>]
- [-PartitionKey <String[]>] [<CommonParameters>]
+ [-PartitionKey <String[]>] [-Encoding <String>] [<CommonParameters>]
 ```
 
 ### Account
 
 ```powershell
 New-CosmosDbDocument -Account <String> [-KeyType <String>] [-Key <SecureString>] [-Database <String>]
  -CollectionId <String> -DocumentBody <String> [-IndexingDirective <String>] [-Upsert <Boolean>]
- [-PartitionKey <String[]>] [<CommonParameters>]
+ [-PartitionKey <String[]>] [-Encoding <String>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -65,6 +65,21 @@ PS C:\> New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'Partitione
 
 Create a new document in the 'en-us' in a partitioned collection in a database.
 
+### Example 3
+
+```powershell
+PS C:\> $document = @"
+{
+    `"id`": `"en-us`",
+    `"content`": `"杉本 司`"
+}
+"@
+PS C:\> New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'PartitionedCollection' -DocumentBody $document -Encoding 'UTF-8'
+```
+
+Create a new document containing UTF-8 encoded strings in a non-partitioned collection
+in a database.
+
 ## PARAMETERS
 
 ### -Context
@@ -240,6 +255,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Encoding
+
+This parameter allows the Encoding to be set to UTF-8 for documents that contain
+non-ASCII characters. If this parameter is not specified the default encoding is
+used.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+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.

docs/Set-CosmosDbDocument.md

@@ -18,15 +18,15 @@ 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 <String>]
- [<CommonParameters>]
+ [-Encoding <String>] [<CommonParameters>]
 ```
 
 ### Account
 
 ```powershell
 Set-CosmosDbDocument -Account <String> [-Database <String>] [-Key <SecureString>] [-KeyType <String>]
  -CollectionId <String> -Id <String> -DocumentBody <String> [-IndexingDirective <String>]
- [-PartitionKey <String>] [<CommonParameters>]
+ [-PartitionKey <String>] [-Encoding <String>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -50,6 +50,21 @@ PS C:\> Set-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewColle
 
 Replace the content of a document in a collection in the database.
 
+### Example 2
+
+```powershell
+PS C:\> $newDocument = @"
+{
+    `"id`": `"ac12345`",
+    `"content`": `"杉本 司`"
+}
+"@
+PS C:\> Set-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id 'ac12345' -DocumentBody $newDocument -Encoding 'UTF-8'
+```
+
+Replace the content of a document in a collection in the database with a
+document using UTF-8 encoding.
+
 ## PARAMETERS
 
 ### -Context
@@ -70,6 +85,7 @@ Accept wildcard characters: False
 ```
 
 ### -Account
+
 The account name of the Cosmos DB to access.
 
 ```yaml
@@ -85,6 +101,7 @@ Accept wildcard characters: False
 ```
 
 ### -Database
+
 The name of the database to access in the Cosmos DB account.
 
 ```yaml
@@ -100,6 +117,7 @@ Accept wildcard characters: False
 ```
 
 ### -Key
+
 The key to be used to access this Cosmos DB.
 
 ```yaml
@@ -115,6 +133,7 @@ Accept wildcard characters: False
 ```
 
 ### -KeyType
+
 The type of key that will be used to access ths Cosmos DB.
 
 ```yaml
@@ -130,6 +149,7 @@ Accept wildcard characters: False
 ```
 
 ### -CollectionId
+
 This is the Id of the collection to update the document for.
 
 ```yaml
@@ -145,6 +165,7 @@ Accept wildcard characters: False
 ```
 
 ### -Id
+
 This is the Id of the document to update.
 
 ```yaml
@@ -160,6 +181,7 @@ Accept wildcard characters: False
 ```
 
 ### -DocumentBody
+
 This is the body of the document to update.
 It must be
 formatted as a JSON string and contain the Id value of the
@@ -178,6 +200,7 @@ Accept wildcard characters: False
 ```
 
 ### -IndexingDirective
+
 Include includes the document in the indexing path while
 Exclude omits the document from indexing.
 
@@ -194,6 +217,7 @@ Accept wildcard characters: False
 ```
 
 ### -PartitionKey
+
 The partition key value for the document to be deleted.
 Required if and must be specified only if the collection is
 created with a partitionKey definition.
@@ -210,6 +234,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Encoding
+
+This parameter allows the Encoding to be set to UTF-8 for documents that contain
+non-ASCII characters. If this parameter is not specified the default encoding is
+used.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+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).

src/lib/documents.ps1

@@ -247,8 +247,10 @@ function Get-CosmosDbDocument
             }
         }
 
-        # Because the headers of this request will contain important information
-        # then we need to use a plain web request.
+        <#
+            Because the headers of this request will contain important information
+            then we need to use a plain web request.
+        #>
         $result = Invoke-CosmosDbRequest @PSBoundParameters `
             -Method $method `
             -ResourceType 'docs' `
@@ -326,7 +328,12 @@ function New-CosmosDbDocument
         [Parameter()]
         [ValidateNotNullOrEmpty()]
         [System.String[]]
-        $PartitionKey
+        $PartitionKey,
+
+        [Parameter()]
+        [ValidateSet('Default', 'UTF-8')]
+        [System.String]
+        $Encoding = 'Default'
     )
 
     $null = $PSBoundParameters.Remove('CollectionId')
@@ -500,7 +507,12 @@ function Set-CosmosDbDocument
         [Parameter()]
         [ValidateNotNullOrEmpty()]
         [System.String]
-        $PartitionKey
+        $PartitionKey,
+
+        [Parameter()]
+        [ValidateSet('Default', 'UTF-8')]
+        [System.String]
+        $Encoding = 'Default'
     )
 
     $null = $PSBoundParameters.Remove('CollectionId')