Merge pull request #21 from dmilov/topic/dmilov/update-readme-examples

Author: Michael Gasch

README.md

@@ -8,15 +8,15 @@ Supported CloudEvents versions:
 Supported Protocols:
 - HTTP
 
-# **CloudEvents.Sdk** Module
+## **`CloudEvents.Sdk`** Module
 The module contains functions to
 - Create CloudEvent objects
 - Add data to a CloudEvent object
 - Read data from a CloudEvent object
 - Convert a CloudEvent object to an HTTP Message
 - Convert an HTTP Message to a CloudEvent object
 
-## Install **CloudEvents.Sdk** Module
+## Install **`CloudEvents.Sdk`** Module
 
 ### Prerequisites
 - [PowerShell 7.0](https://github.com/PowerShell/PowerShell/releases/tag/v7.0.4)
@@ -38,174 +38,124 @@ Function        Set-CloudEventJsonData                             0.2.0      Cl
 Function        Set-CloudEventXmlData                              0.2.0      CloudEvents.Sdk
 ```
 
-## Event Producer
+## Using **`CloudEvents.Sdk`** Module
+## 1. Event Producer
 ### Create a CloudEvent object
 ```powershell
-$cloudEvent = New-CloudEvent -Type 'com.example.object.deleted.v2' -Source 'mailto:[email protected]' -Id '6e8bc430-9c3a-11d9-9669-0800200c9a66' -Time (Get-Date)
+$cloudEvent = New-CloudEvent -Type 'com.example.object.deleted.v2' -Source 'mailto:[email protected]' -Id (New-Guid).Guid -Time (Get-Date)
 ```
 
-### Add **JSON Data** to a CloudEvent object
+### Set **JSON Data** to a CloudEvent object
 ```powershell
-$cloudEvent | Add-CloudEventJsonData -Data @{
-   'key1' = 'value1'
-   'key2' = @{
-      'key3' = 'value3'
-   }
+$cloudEvent | Set-CloudEventJsonData -Data @{
+    'Foo' = 'Hello'
+    'Bar' = 'World'
 }
+
+
+DataContentType : application/json
+Data            : {
+                    "Bar": "World",
+                    "Foo": "Hello"
+                  }
+Id              : ac9b12d9-ae45-4654-a4d7-42bbf0d9816d
+DataSchema      :
+Source          : mailto:[email protected]
+SpecVersion     : V1_0
+Subject         :
+Time            : 4/26/2021 9:00:45 AM
+Type            : com.example.object.deleted.v2
 ```
 
-### Add **XML Data** to a CloudEvent object
+### Set **XML Data** to a CloudEvent object
 ```powershell
-$cloudEvent | Add-CloudEventXmlData -Data @{
-   'key1' = @{
-      'key2' = 'value'
-   }
+$cloudEvent | Set-CloudEventXmlData -Data @{
+    'xml' = @{
+        'Foo' = 'Hello'
+        'Bar' = 'World'
+    }    
 } `
 -AttributesKeysInElementAttributes $true
+
+
+DataContentType : application/xml
+Data            : <xml><Bar>World</Bar><Foo>Hello</Foo></xml>
+Id              : ac9b12d9-ae45-4654-a4d7-42bbf0d9816d
+DataSchema      :
+Source          : mailto:[email protected]
+SpecVersion     : V1_0
+Subject         :
+Time            : 4/26/2021 9:00:45 AM
+Type            : com.example.object.deleted.v2
 ```
-`AttributesKeysInElementAttributes` specifies how to format the XML. If `true` and the input Data hashtable has pairs of 'Attributes', 'Value' keys creates XML element with attributes, otherwise each key is formatted as XML element.<br/>
-If `true`
-```powershell
-   @{'root' = @{'Attributes' = @{'att1' = 'true'}; 'Value' = 'val-1'}}
-```
-is formatted as
-```xml
-<root att1="true">val-1</root>
-```
-If `false`
+### Set Custom Format Data to a CloudEvent object
 ```powershell
-@{'root' = @{'Attributes' = @{'att1' = 'true'}; 'Value' = 'val-1'}}
-```
-is formatted as
-```xml
-<root><Attributes><att1>true</att1></Attributes><Value>val-1</Value></root>
-```
+$cloudEvent | Set-CloudEventData -DataContentType 'application/text' -Data 'Hello World!'
 
-#### Add Custom Format Data to a CloudEvent object
-```powershell
-$cloudEvent | Add-CloudEventData -DataContentType 'application/text' -Data 'wow'
+DataContentType : application/text
+Data            : Hello World!
+Id              : b1b748cd-e98d-4f5f-80ea-76dea71a53a5
+DataSchema      :
+Source          : mailto:[email protected]
+SpecVersion     : V1_0
+Subject         :
+Time            : 4/27/2021 7:00:44 PM
+Type            : com.example.object.deleted.v2
 ```
 
 ### Convert a CloudEvent object to an HTTP message in **Binary** or **Structured** content mode
 ```powershell
-$cloudEventBinaryHttpMessage = $cloudEvent | ConvertTo-HttpMessage -ContentMode Binary
+# Format structured cloud event HTTP message
 $cloudEventStructuredHttpMessage = $cloudEvent | ConvertTo-HttpMessage -ContentMode Structured
 ```
 
 ### Send CloudEvent object to HTTP server
 ```powershell
-Invoke-WebRequest -Method POST -Uri 'http://my.cloudevents.server/' -Headers $cloudEventBinaryHttpMessage.Headers -Body $cloudEventBinaryHttpMessage.Body
+Invoke-WebRequest -Method POST -Uri 'http://my.cloudevents.server/' -Headers $cloudEventStructuredHttpMessage.Headers -Body $cloudEventStructuredHttpMessage.Body
 ```
 
-## Event Consumer
+## 2. Event Consumer
 ### Convert an HTTP message to a CloudEvent object
 ```powershell
 $cloudEvent = ConvertFrom-HttpMessage -Headers <headers> -Body <body>
 ```
 
 ### Read CloudEvent **JSON Data** as a **PowerShell Hashtable**
 ```powershell
-$hashtableData = Read-CloudEventJsonData -CloudEvent $cloudEvent
+Read-CloudEventJsonData -CloudEvent $cloudEvent
+
+
+Name                           Value
+----                           -----
+Foo                            Hello
+Bar                            World
 ```
 
 ### Read CloudEvent **XML Data** as a **PowerShell Hashtable**
 ```powershell
-$hashtableData = Read-CloudEventXmlData -CloudEvent $cloudEvent -ConvertMode SkipAttributes
-```
-The `ConvertMode` parameter specifies how the XML to be represented in the result hashtable<br/>
-`SkipAttributes` - Skips attributes of the XML elements. XmlElement is a Key-Value pair where Key is the Xml element name, and the value is the Xml element inner text<br/>
-Example:
-```xml
-<key att='true'>value1</key>
-```
-is converted to
-```powershell
-@{'key' = 'value-1'}
-```
-`AlwaysAttrValue` - Each element is a HashTable with two keys<br/>
-        'Attributes' - key-value pair of the Xml element attributes if any, otherwise null<br/>
-        'Value' - string value represinting the xml element inner text<br/>
-Example:
-```xml
-```
-<key1 att='true'>value1</key1><key2>value2</key2>
-is converted to
-```powershell
-@{
-   'key1' = @{
-      'Attributes' = @{
-         'att' = 'true'
-      }
-      'Value' = 'value1'
-   }
-   'key2' = @{
-      'Attributes' = $null
-      'Value' = 'value2'
-   }
-}
-```
-`AttrValueWhenAttributes` - Uses `SkipAttributes` for xml elements without attributes and `AlwaysAttrValue` for xml elements with attributes<br/>
-Example:
-```xml
-<key1 att='true'>value1</key1><key2>value2</key2>
-```
-is converted to
-```powershell
-@{
-   'key1' = @{
-      'Attributes' = @{
-         'att' = 'true'
-      }
-      'Value' = 'value1'
-   }
-   'key2' = 'value2'
-}
-```
+Read-CloudEventXmlData -CloudEvent $cloudEvent -ConvertMode SkipAttributes
 
-### Read CloudEvent Custom Format **Data** as a **byte[]**
-```powershell
-$bytes = Read-CloudEventData -CloudEvent $cloudEvent
+Name                           Value
+----                           -----
+xml                            {Bar, Foo}
 ```
 
-## Build the **CloudEvents.Sdk** Module
-
-The `build.ps1` script
-- Creates the CloudEvents PowerShell Module in a `CloudEvents` directory.
-- Runs functions unit tests
-- Runs local integrations tests
-- Creates a catalog file for the CloudEvents Module
-
-### Prerequisites
-- [PowerShell 7.0](https://github.com/PowerShell/PowerShell/releases/tag/v7.0.4)
-- [Pester 5.1.1](https://www.powershellgallery.com/packages/Pester/5.1.1)
-- [dotnet SDK](https://dotnet.microsoft.com/download/dotnet/5.0)
+The `ConvertMode` parameter specifies how the xml should be converted to a PowerShell Hashtable. `SkipAttributes` mode skips reading the xml attributes. There are three different modes of conversion. For more details check the help of the `Read-CloudEventXmlData` cmdlet.
 
+### Read CloudEvent Custom Format **Data** as a **byte[]**
 ```powershell
-> ./build.ps1
-[9:52:42 AM] INFO: Publish CloudEvents.Sdk Module to 'C:\git-repos\cloudevents\cloudevents-sdk-powershell\CloudEvents.Sdk'
-Microsoft (R) Build Engine version 16.8.3+39993bd9d for .NET
-Copyright (C) Microsoft Corporation. All rights reserved.
-
-  Determining projects to restore...
-  All projects are up-to-date for restore.
-  CloudEventsPowerShell -> C:\git-repos\cloudevents\cloudevents-sdk-powershell\src\CloudEventsPowerShell\bin\Release\netstandard2.0\CloudEventsPowerShell.dll
-  CloudEventsPowerShell -> C:\git-repos\cloudevents\cloudevents-sdk-powershell\CloudEvents.Sdk\
-[9:52:44 AM] INFO: Run unit tests
-
-Starting discovery in 9 files.
-Discovery finished in 294ms.
-[+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\Add-CloudEventData.Tests.ps1 1.01s (184ms|656ms)
-[+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\Add-CloudEventJsonData.Tests.ps1 329ms (39ms|279ms)   [+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\Add-CloudEventXmlData.Tests.ps1 336ms (58ms|267ms)    [+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\ConvertFrom-HttpMessage.Tests.ps1 557ms (203ms|337ms) [+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\ConvertTo-HttpMessage.Tests.ps1 508ms (132ms|361ms)   [+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\New-CloudEvent.Tests.ps1 275ms (22ms|243ms)
-[+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\Read-CloudEventData.Tests.ps1 257ms (10ms|236ms)
-[+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\Read-CloudEventJsonData.Tests.ps1 308ms (40ms|257ms)
-[+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\unit\Read-CloudEventXmlData.Tests.ps1 310ms (53ms|246ms)
-Tests completed in 3.94s
-Tests Passed: 28, Failed: 0, Skipped: 0 NotRun: 0
-[9:52:49 AM] INFO: Run integration tests
-
-Starting discovery in 1 files.
-Discovery finished in 176ms.
-[+] C:\git-repos\cloudevents\cloudevents-sdk-powershell\test\integration\HttpIntegration.Tests.ps1 2.54s (1.77s|617ms)
-Tests completed in 2.56s
-Tests Passed: 5, Failed: 0, Skipped: 0 NotRun: 0
+Read-CloudEventData -CloudEvent $cloudEvent
+
+72
+101
+108
+108
+111
+32
+87
+111
+114
+108
+100
+33
 ```