Issue #12 - Create a beginning set of documentation. Help added to th…

…e exported functions and README.md created.

PshOdata.psm1

@@ -25,6 +25,46 @@ $paramignorelist = @('PipelineVariable','OutBuffer','OutVariable','WarningVariab
                      'ErrorAction','Debug','Verbose')
 
 function New-PshOdataClass {
+<#
+ .Synopsis
+ Creates a PowerShell representation of an Odata class
+
+ .Description
+ In order to create an odata endpoint, you must first create a class, add GET, UPDATE, CREATE, and/or DELETE
+ methods for the class, and finally generate the odata files by creating the odata endpoint.
+
+ New-PshOdataClass is used to create the odata class.  It specifies what properties are available.  This acts
+ as a sort of Select-Object for the GET method that you will create for the class.
+
+ .Parameter Name
+ The name of the class.  This will be the name used in your odata url, e.g., http://server/odata/classname
+
+ .Parameter PK
+ Every odata endpoint must have a primary key.  This must be a unique identifier for the class.  If the cmdlet
+ you are using does not have a unique value, you will need to wrap the cmdlet in another cmdlet that will add
+ a primary key before you can create a get method for the class.
+
+ .Parameter Properties
+ This is the list of properties that will be available to the class.  This can be thought of as a Select-Object
+ after your get- cmdlet.  Regardless of what your cmdlet returns, only the properties listed will be visible
+ when viewing the objects for the class.
+
+ .Inputs
+ Strings
+
+ .Outputs
+ PSObject
+
+ .Example
+ The following is a class that can be used to represent a ProcessInfo object.  This class may be used with 
+ a GET method that is returned by the Get-Process cmdlet.
+
+ New-PshOdataClass Process -PK ID -Properties 'Name','ID'
+
+ .LINK
+ https://github.com/toenuff/PshOdata/
+
+#>
 	param(
 		[Parameter(Mandatory=$true, Position=0)]
 		[string] $Name,
@@ -43,6 +83,77 @@ function New-PshOdataClass {
 }
 
 function Set-PshOdataMethod {
+<#
+ .Synopsis
+ This cmdlet adds a GET, DELETE, UPDATE, or CREATE method to the class
+
+ .Description
+ This cmdlet binds one of the HTTP verbs, i.e., GET, DELETE, UPDATE, or CREATE, to a cmdlet that is installed on the
+ local system.  The cmdlet must be in a module in order for it to work.  The method will be added to a PshOdataClass
+ PSObject that is created by New-PshOdataClass.
+
+ .Parameter InputObject
+ This is the class that you are setting the method for.  This is generally the object returned from New-PshOdataClass
+
+ .Parameter Verb
+ This is the HTTP verb for the method you are setting.  It must be either GET, DELETE, UPDATE, or CREATE. 
+ 
+ Currently only GET and DELETE have been proven to work
+
+ .Parameter Params
+ This is only supported with the Get method.  It will allow you to pass a specific parameter to a cmdlet via the
+ following syntax in the url:
+
+ http://servername/odata/classname?paramname=value
+
+ .Parameter FilterParams
+ This is a special parameter that can be used with odata filters.  Filtering can be done with any property of the
+ Odata class.  However, if you use a filter parameter, it will ensure that the filter is applied by calling the 
+ associated cmdlet with the parametername specified.  This only works with the GET method.  
+ 
+ This will allow you to use the following url:
+ 
+ http://servername/odata/classname?$filter=(FilterParam eq 'value')
+ This will call 
+ cmdletname -FilterParam value
+
+ Delete methods should have a FilterParam for the primary key specified in order for Delete to work.  If your
+ cmdlet does not take the PK as a property, you will need to wrap the function in another cmdlet that will accept
+ the PK.
+
+ .Parameter Cmdlet
+ This is the cmdlet that the method will invoke under the covers.  The cmdlet must be in a module in order for it to
+ work.
+
+ .Inputs
+ PSObject
+
+ .Outputs
+ PSObject
+
+ .Example
+ The following will add a get method that uses get-process.  It will allow name and ID parameters, and it will
+ allow Name to be used as a parameter if a filter is specified in the URL.
+
+ $class |Set-PshOdataMethod -verb get -cmdlet get-process -Params Name, ID -FilterParams Name
+
+ The above will allow the following urls:
+ http://servername/odata/Process
+ http://servername/odata/Process?Name=notepad
+ http://servername/odata/Process?ID=3212
+
+ .Example
+ The following will create a delete method that runs stop-process:
+
+ $class |Set-PshOdataMethod -verb delete -cmdlet stop-process -FilterParams ID
+
+ The above will allow the delete verb to be passed to the following URL:
+ http://servername/odata/Process('3333')
+
+ .LINK
+ https://github.com/toenuff/PshOdata/
+
+#>
 	param(
 		[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
 		[PSObject[]] $InputObject,
@@ -79,9 +190,75 @@ function Set-PshOdataMethod {
 }
 
 function New-PshOdataEndpoint {
+<#
+ .Synopsis
+ Creates an odata endpoint from a collection of defined Odata class objects with methods
+
+ .Description
+ This cmdlet is used in conjunction with New-PshOdataClass and Set-PshOdataMethod.  When New-PshOdataEndpoint is called,
+ the following three files are created:
+
+     Schema.mof - a document that describes the properties and PK for the classes in the endpoint.
+     Schema.xml - a document that describes details about the methods and underlying PowerShell cmdlets that will be called through the endpoint.
+     RbacConfiguration.xml - a document that describes which modules to load.  This set of cmdlets assumes that the underlying modules are
+        located in c:\windows\system32\WindowsPowerShell\modules.
+
+ These files need to be manually copied to the folder of an IIS server that is configured with an application that is using the Odata IIS extensions.
+ An IISreset is also required.
+
+ .Parameter Path
+ The folder where you would like to save the schema.mof, schema.xml, and RbacConfiguration.xml files too. This defaults to an odata folder in
+ the current working directory
+
+ .Parameter PshOdataClasses
+ A collection of PshOdata classes with methods that are set for the classes.  This generally comes from the output of New-PshOdataClass and
+ Set-PshOdataMethod.
+
+ .Parameter Force
+ This is used to overwrite the output files if they already exist.
+ 
+ .Inputs
+ PSObject
+
+ .Outputs
+ Three files: Schema.mof, Schema.xml, and RbaConfiguration 
+
+ .Example
+ $class = New-PshOdataClass Process -PK ID -Properties 'Name','ID'
+ $class |Set-PshOdataMethod -verb get -cmdlet get-process -Params Name, ID -FilterParams Name
+ $class |Set-PshOdataMethod -verb delete -cmdlet stop-process -FilterParams ID
+ $class | New-PshOdataEndpoint
+
+ The above will create the files required to allow GET and SET http methods to a url like this:
+  http://server/odata/Process
+  http://server/odata/Process('3333') # 3333 is the ID of the process you would like to retrieve.  This is the only url that works for delete.
+  http://server/odata/Process?name=notepad
+  http://server/odata/Process?$filter=(name eq 'notepad')
+  http://server/odata/Process?$format=application/json;odata=verbose #Used to render JSON instead of XML
+
+ The endpoint will return Process objects that contain Name and ID Properties that are taken from Get-Process.  It will also allow the DELETE
+ method to call Stop-Process when the PK is used.
+
+ .Example
+ The following creates the files required for an Odata Endpoint that serves Process and Service objects that are returned from Get-Process and Get-Service
+ $classes = @()
+ $classes += New-PshOdataClass Process -PK ID -Properties 'Name', 'ID' |Set-PshOdataMethod -verb get -cmdlet get-process -Params Name, ID -FilterParams Name
+ $classes += New-PshOdataClass Service -PK Name -Properties 'Status', 'Name', 'Displayname' |Set-PshOdataMethod -verb get -cmdlet get-Service -Params Name -FilterParams Name
+ $classes |New-PshOdataEndpoint
+
+ .Example
+ The following script will create the files required for an Odata endpoint directly into c:\inetpub\wwwroot\odata.  If the files exist already, 
+ they will be overwritten.
+
+ $class |New-PshOdataEndpoint -Path c:\inetpub\wwwroot\odata -Force
+
+ .LINK
+ https://github.com/toenuff/PshOdata/
+
+#>
 	param(
 		[Parameter(Mandatory=$false, ValueFromPipeline=$true)]
-		[PsObject[]] $OdataClasses,
+		[PsObject[]] $PshOdataClasses,
 		[Parameter(Mandatory=$false, position=0)]
 		[string]$Path = "odata",
 		[Switch]$Force
@@ -96,7 +273,7 @@ function New-PshOdataEndpoint {
 		$classes = @()
 	}
 	PROCESS {
-		$classes += $OdataClasses
+		$classes += $PshOdataClasses
 	}
 	END {
 		$mof = ""

README.md

@@ -0,0 +1,60 @@
+# PshOdata Module
+
+2008R2 and 2012 versions of Windows contain a feature called IIS Odata Extensions.  An IIS application that uses the extensions can be configured to create a RESTful web service that will run PowerShell cmdlets and return the objects as either JSON or XML.  The PshOdata Module makes it easy to generate the files used to create these endpoints.
+
+## Example Usage
+> $class |Set-PshOdataMethod -verb get -cmdlet get-process -Params Name, ID -FilterParams Name
+> $class |Set-PshOdataMethod -verb delete -cmdlet stop-process -FilterParams ID
+> $class | New-PshOdataEndpoint
+
+The above will create the files required to allow GET and SET http methods to a url like this:
+* http://server/odata/Process
+* http://server/odata/Process('3333') # 3333 is the ID of the process you would like to retrieve.  This is the only url that works for delete.
+* http://server/odata/Process?name=notepad
+* http://server/odata/Process?$filter=(name eq 'notepad')
+* http://server/odata/Process?$format=application/json;odata=verbose #Used to render JSON instead of XML
+
+The endpoint will return Process objects that contain Name and ID Properties that are taken from Get-Process.  It will also allow the DELETE
+method to call Stop-Process when the PK is used.
+
+## Files Generated
+
+The New-PshOdataEndpoint function will create a set of files in an odata folder within the current working directory by default.
+
+The following files are generated:
+* Schema.mof - a document that describes the properties and PK for the classes in the endpoint.
+* Schema.xml - a document that describes details about the methods and underlying PowerShell cmdlets that will be called through the endpoint.
+* RbacConfiguration.xml - a document that describes which modules to load.  This set of cmdlets assumes that the underlying modules are located in c:\windows\system32\WindowsPowerShell\modules.
+
+## Installation of the files
+
+Currently, we do not have a method to create the IIS portion of the Odata extensions.  We plan on solving this with a function soon.  However, in the meantime, you can use the OdataSchemaDesigner in order to have your first endpoint created, and then you can use these cmdlets to generate the files you need for your Odata service.
+
+The following steps must be performed on Windows Server 2012 box that does NOT have R2.
+
+1. Add-WindowsFeature ManagementOdata # Install the odata extensions
+1. Install Visual Studio Isolated Shell - http://www.microsoft.com/en-us/download/details.aspx?id=1366
+1. Install the odata extension isolated installer - http://archive.msdn.microsoft.com/mgmtODataWebServ/Release/ProjectReleases.aspx?ReleaseId=5877
+1. Launch the Management Odata Schema Designer from the start screen
+   1. File-> New File -> Management Odata Model
+   1. Right-Click and select Import Cmdlets
+   1. Local Computer -> Next
+   1. Installed Windows PowerShell Modules -> Microsoft.PowerShell.Management
+   1. Choose Service -> Next
+   1. Uncheck CREATE and UPDATE.  Only Get should be selected. Next.
+   1. Next
+   1. Choose any key and click Next.
+   1. Next
+   1. Finish
+   1. Right click in the designer and choose Publish Odata Endpoint
+   1. Select the local computername and fill out a username and password.  Choose a name for the site (odata is a good choice).  Finally select a port number and then click Publish.
+
+Once the IIS server has the site created.  You can use the cmdlets in this module to generate the schema.xml, schema.mof, and rbacconfiguration.xml files.  Copy these files into the application you created (c:\inetpub\wwwroot\odata).  Perform an IISReset.  Enjoy your web service.
+
+## Notes
+
+* Currently only GET and DELETE is supported
+* Use *Get-Command -Module PshOdata* in order to see the cmdlets in the module
+* Use *Get-Help cmdletname -full* in order to see the full set of documenation along with examples you can try
+* Odata classes require a primary key.  This needs to be a unique value for each object returned.  If one does not exist for the data you are retrieving from PowerShell, you will need to create a wrapper function in a new module that calls your function and creates a primary key.  You can then create a method based on this new cmdlet.
+* When creating a DELETE method, you may only use the PK as a parameter.  Your delete cmdlet must support this.