cloudevents
/
sdk-powershell
mirror of https://github.com/cloudevents/sdk-powershell.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve examples. Remove unnecessary details. 

Signed-off-by: Dimitar Milov <dmilov@vmware.com>
This commit is contained in:
Dimitar Milov 2021-04-26 09:39:47 +03:00 committed by dimitar
parent 37a83536a2
commit 3a9010a9a5
1 changed files with 82 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
README.md
View File

@ -8,7 +8,7 @@ Supported CloudEvents versions:
Supported Protocols: Supported Protocols:
- HTTP - HTTP
# **CloudEvents.Sdk** Module ## **`CloudEvents.Sdk`** Module
The module contains functions to The module contains functions to
- Create CloudEvent objects - Create CloudEvent objects
- Add data to a CloudEvent object - Add data to a CloudEvent object
@ -16,7 +16,7 @@ The module contains functions to
- Convert a CloudEvent object to an HTTP Message - Convert a CloudEvent object to an HTTP Message
- Convert an HTTP Message to a CloudEvent object - Convert an HTTP Message to a CloudEvent object
## Install **CloudEvents.Sdk** Module ## Install **`CloudEvents.Sdk`** Module
### Prerequisites ### Prerequisites
- [PowerShell 7.0](https://github.com/PowerShell/PowerShell/releases/tag/v7.0.4) - [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 Function Set-CloudEventXmlData 0.2.0 CloudEvents.Sdk
``` ```
## Event Producer ## Using **`CloudEvents.Sdk`** Module
## 1. Event Producer
### Create a CloudEvent object ### Create a CloudEvent object
```powershell ```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 ```powershell
$cloudEvent | Add-CloudEventJsonData -Data @{ $cloudEvent | Set-CloudEventJsonData -Data @{
'key1' = 'value1' 'Foo' = 'Hello'
'key2' = @{ 'Bar' = 'World'
'key3' = 'value3'
}
} }
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 ```powershell
$cloudEvent | Add-CloudEventXmlData -Data @{ $cloudEvent | Set-CloudEventXmlData -Data @{
'key1' = @{ 'xml' = @{
'key2' = 'value' 'Foo' = 'Hello'
} 'Bar' = 'World'
}
} ` } `
-AttributesKeysInElementAttributes $true -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.<br/>
If `true`
```powershell
@{'root' = @{'Attributes' = @{'att1' = 'true'}; 'Value' = 'val-1'}}
```
is formatted as
```xml
<root att1="true">val-1</root>
```
If `false`
```powershell
@{'root' = @{'Attributes' = @{'att1' = 'true'}; 'Value' = 'val-1'}}
```
is formatted as
```xml
<root><Attributes><att1>true</att1></Attributes><Value>val-1</Value></root>
```
#### Add Custom Format Data to a CloudEvent object
DataContentType : application/xml
Data : <xml><Bar>World</Bar><Foo>Hello</Foo></xml>
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 ```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 ### Convert a CloudEvent object to an HTTP message in **Binary** or **Structured** content mode
```powershell ```powershell
$cloudEventBinaryHttpMessage = $cloudEvent | ConvertTo-HttpMessage -ContentMode Binary # Format structured cloud event HTTP message
$cloudEventStructuredHttpMessage = $cloudEvent | ConvertTo-HttpMessage -ContentMode Structured $cloudEventStructuredHttpMessage = $cloudEvent | ConvertTo-HttpMessage -ContentMode Structured
``` ```
### Send CloudEvent object to HTTP server ### Send CloudEvent object to HTTP server
```powershell ```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 ### Convert an HTTP message to a CloudEvent object
```powershell ```powershell
$cloudEvent = ConvertFrom-HttpMessage -Headers <headers> -Body <body> $cloudEvent = ConvertFrom-HttpMessage -Headers <headers> -Body <body>
@ -105,107 +122,40 @@ $cloudEvent = ConvertFrom-HttpMessage -Headers <headers> -Body <body>
### Read CloudEvent **JSON Data** as a **PowerShell Hashtable** ### Read CloudEvent **JSON Data** as a **PowerShell Hashtable**
```powershell ```powershell
$hashtableData = Read-CloudEventJsonData -CloudEvent $cloudEvent Read-CloudEventJsonData -CloudEvent $cloudEvent
Name Value
---- -----
Foo Hello
Bar World
``` ```
### Read CloudEvent **XML Data** as a **PowerShell Hashtable** ### Read CloudEvent **XML Data** as a **PowerShell Hashtable**
```powershell ```powershell
$hashtableData = Read-CloudEventXmlData -CloudEvent $cloudEvent -ConvertMode SkipAttributes Read-CloudEventXmlData -CloudEvent $cloudEvent -ConvertMode SkipAttributes
```
The `ConvertMode` parameter specifies how the XML to be represented in the result hashtable<br/> Name Value
`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 {Bar, Foo}
```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'
}
``` ```
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[]** ### Read CloudEvent Custom Format **Data** as a **byte[]**
```powershell ```powershell
$bytes = Read-CloudEventData -CloudEvent $cloudEvent Read-CloudEventData -CloudEvent $cloudEvent
```
## Build the **CloudEvents.Sdk** Module 72
101
The `build.ps1` script 108
- Creates the CloudEvents PowerShell Module in a `CloudEvents` directory. 108
- Runs functions unit tests 111
- Runs local integrations tests 32
- Creates a catalog file for the CloudEvents Module 87
111
### Prerequisites 114
- [PowerShell 7.0](https://github.com/PowerShell/PowerShell/releases/tag/v7.0.4) 108
- [Pester 5.1.1](https://www.powershellgallery.com/packages/Pester/5.1.1) 100
- [dotnet SDK](https://dotnet.microsoft.com/download/dotnet/5.0) 33
```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
``` ```