diff --git a/README.md b/README.md index 60a8bec..374ff05 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ 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 @@ -16,7 +16,7 @@ The module contains functions to - 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,66 +38,83 @@ 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:cncf-wg-serverless@lists.cncf.io' -Id '6e8bc430-9c3a-11d9-9669-0800200c9a66' -Time (Get-Date) +$cloudEvent = New-CloudEvent -Type 'com.example.object.deleted.v2' -Source 'mailto:cncf-wg-serverless@lists.cncf.io' -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:cncf-wg-serverless@lists.cncf.io +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 -``` -`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.
-If `true` -```powershell - @{'root' = @{'Attributes' = @{'att1' = 'true'}; 'Value' = 'val-1'}} -``` -is formatted as -```xml -val-1 -``` -If `false` -```powershell -@{'root' = @{'Attributes' = @{'att1' = 'true'}; 'Value' = 'val-1'}} -``` -is formatted as -```xml -trueval-1 -``` -#### Add Custom Format Data to a CloudEvent object + +DataContentType : application/xml +Data : WorldHello +Id : ac9b12d9-ae45-4654-a4d7-42bbf0d9816d +DataSchema : +Source : mailto:cncf-wg-serverless@lists.cncf.io +SpecVersion : V1_0 +Subject : +Time : 4/26/2021 9:00:45 AM +Type : com.example.object.deleted.v2 +``` +### Set Custom Format Data to a CloudEvent object ```powershell -$cloudEvent | Add-CloudEventData -DataContentType 'application/text' -Data 'wow' +$cloudEvent | Set-CloudEventData -DataContentType 'application/text' -Data 'Hello World!' + +DataContentType : application/text +Data : Hello World! +Id : b1b748cd-e98d-4f5f-80ea-76dea71a53a5 +DataSchema : +Source : mailto:cncf-wg-serverless@lists.cncf.io +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 -Body @@ -105,107 +122,40 @@ $cloudEvent = ConvertFrom-HttpMessage -Headers -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
-`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
-Example: -```xml -value1 -``` -is converted to -```powershell -@{'key' = 'value-1'} -``` -`AlwaysAttrValue` - Each element is a HashTable with two keys
- 'Attributes' - key-value pair of the Xml element attributes if any, otherwise null
- 'Value' - string value represinting the xml element inner text
-Example: -```xml -``` -value1value2 -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
-Example: -```xml -value1value2 -``` -is converted to -```powershell -@{ - 'key1' = @{ - 'Attributes' = @{ - 'att' = 'true' - } - 'Value' = 'value1' - } - 'key2' = 'value2' -} +Read-CloudEventXmlData -CloudEvent $cloudEvent -ConvertMode SkipAttributes + +Name Value +---- ----- +xml {Bar, Foo} ``` +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 -$bytes = Read-CloudEventData -CloudEvent $cloudEvent -``` +Read-CloudEventData -CloudEvent $cloudEvent -## 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) - -```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 +72 +101 +108 +108 +111 +32 +87 +111 +114 +108 +100 +33 ``` \ No newline at end of file