Skip to content

Improve examples. Remove unnecessary details. #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
embano1 merged 1 commit into from
Apr 28, 2021
Merged

Improve examples. Remove unnecessary details. #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 81 additions & 131 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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: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


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
```
`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: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
Copy link
Member

@embano1 embano1 Apr 27, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the example uses a Structured CloudEvent, are Headers actually used at all in this example? What is contained in the Headers of a structured CE? Just curious :)

Do we need to show two examples, e.g. using Headers+Body for binary mode?

Copy link
Contributor Author

@dmilov dmilov Apr 27, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Headers follow the https://github.com/cloudevents/spec/blob/v1.0.1/http-protocol-binding.md#3-http-message-mapping. In structure mode the ContentType header is application/cloudevents

Do we need to show two examples, e.g. using Headers+Body for binary mode?
Not sure. I can leave only the structure mode?

Copy link
Member

@embano1 embano1 Apr 27, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thx!

```

## 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
```