PowerShell 7.0 SDK for CloudEvents

Go to file

Dimitar Milov f470da2182 Address PR comments from embano1		2021-04-12 10:02:25 +03:00
src/CloudEventsPowerShell	Address PR comments from embano1	2021-04-12 10:02:25 +03:00
test	Rename Add-CloudEventData to Set-CloudEventData	2021-04-09 11:23:22 +03:00
.gitignore	Initial commit	2021-04-07 09:40:42 -07:00
LICENSE	Initial commit	2021-04-07 09:40:42 -07:00
README.md	Remove install instructions from an internal PS repository (#10 )	2021-04-09 10:09:01 +03:00
build.ps1	Adress review comment removing the entire catalog file logic from build.ps1	2021-04-09 18:12:46 +03:00

README.md

PowerShell 7.0 SDK for CloudEvents based on .NET SDK for CloudEvents

Status

Supported CloudEvents versions:

v1.0

Supported Protocols:

HTTP

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

Producer

Create a CloudEvent object

$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)

Add JSON Data to a CloudEvent object

$cloudEvent | Add-CloudEventJsonData -Data @{
   'key1' = 'value1'
   'key2' = @{
      'key3' = 'value3'
   }
}

Add XML Data to a CloudEvent object

$cloudEvent | Add-CloudEventXmlData -Data @{
   'key1' = @{
      'key2' = 'value'
   }
} `
-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

   @{'root' = @{'Attributes' = @{'att1' = 'true'}; 'Value' = 'val-1'}}

is formatted as

<root att1="true">val-1</root>

If false

@{'root' = @{'Attributes' = @{'att1' = 'true'}; 'Value' = 'val-1'}}

is formatted as

<root><Attributes><att1>true</att1></Attributes><Value>val-1</Value></root>

Add Custom Format Data to a CloudEvent object

$cloudEvent | Add-CloudEventData -DataContentType 'application/text' -Data 'wow'

Convert a CloudEvent object to an HTTP message in Binary or Structured content mode

$cloudEventBinaryHttpMessage = $cloudEvent | ConvertTo-HttpMessage -ContentMode Binary
$cloudEventStructuredHttpMessage = $cloudEvent | ConvertTo-HttpMessage -ContentMode Structured

Send CloudEvent object to HTTP server

Invoke-WebRequest -Method POST -Uri 'http://my.cloudevents.server/' -Headers $cloudEventBinaryHttpMessage.Headers -Body $cloudEventBinaryHttpMessage.Body

Consumer

Convert an HTTP message to a CloudEvent object

$cloudEvent = ConvertFrom-HttpMessage -Headers <headers> -Body <body>

Read CloudEvent JSON Data as a PowerShell Hashtable

$hashtableData = Read-CloudEventJsonData -CloudEvent $cloudEvent

Read CloudEvent XML Data as a PowerShell Hashtable

$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:

<key att='true'>value1</key>

is converted to

@{'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:

value1value2 is converted to

@{
   '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:

<key1 att='true'>value1</key1><key2>value2</key2>

is converted to

@{
   'key1' = @{
      'Attributes' = @{
         'att' = 'true'
      }
      'Value' = 'value1'
   }
   'key2' = 'value2'
}

Read CloudEvent Custom Format Data as a byte[]

$bytes = 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

> ./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