PowerShell 7.0 SDK for CloudEvents

Go to file

Dimitar Milov b2afcf89bd Initial commit		2021-04-07 09:40:42 -07:00
src/CloudEventsPowerShell	Initial commit	2021-04-07 09:40:42 -07:00
test	Initial commit	2021-04-07 09:40:42 -07: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	Initial commit	2021-04-07 09:40:42 -07:00
build.ps1	Initial commit	2021-04-07 09:40:42 -07: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 an CloudEvent object to an HTTP Message
Convert an HTTP Message to an 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 represented as 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 represented as a hashtable with two keys
'Attributes' - key-value pair of the cml 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

Install CloudEvents.Sdk Module

$vmwareArtifactoryRepo = 'https://build-artifactory.eng.vmware.com/artifactory/api/nuget/powercli-nuget-local/'

Register-PSRepository -Name 'Artifactory' -SourceLocation $vmwareArtifactoryRepo -PublishLocation $vmwareArtifactoryRepo -InstallationPolicy Trusted

Install-Module CloudEvents.Sdk -Repository Artifactory
Import-Module CloudEvents.Sdk
Get-Command -Module CloudEvents.Sdk

ommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Add-CloudEventData                                 0.1.2      CloudEvents.Sdk
Function        Add-CloudEventJsonData                             0.1.2      CloudEvents.Sdk
Function        Add-CloudEventXmlData                              0.1.2      CloudEvents.Sdk
Function        ConvertFrom-HttpMessage                            0.1.2      CloudEvents.Sdk
Function        ConvertTo-HttpMessage                              0.1.2      CloudEvents.Sdk
Function        New-CloudEvent                                     0.1.2      CloudEvents.Sdk
Function        Read-CloudEventData                                0.1.2      CloudEvents.Sdk
Function        Read-CloudEventJsonData                            0.1.2      CloudEvents.Sdk
Function        Read-CloudEventXmlData                             0.1.2      CloudEvents.Sdk