Merge pull request #1 from Matticusau/initialization

Version 1.0.0.0

CHANGELOG.md

@@ -0,0 +1,10 @@
+
+## 1.0.0-rc (Aug 29, 2017)
+
+  - Initialization of the module
+
+## Background
+
+This changelog is inspired by the
+[Pester](https://raw.githubusercontent.com/pester/Pester/master/CHANGELOG.md) file which in turn was inspired by the [Vagrant](https://github.com/mitchellh/vagrant/blob/master/CHANGELOG.md) file.
+Hopefully this will help keep the releases tidy and understandable.

Examples/ConfigurationSample.Config

@@ -0,0 +1,20 @@
+<Settings ScriptName="ConfigurationSample" Version="1.0">
+    <!-- 
+    A General section to configure general settings for the script
+    -->
+    <General>
+        <LogLevel>1</LogLevel>
+    </General>
+    <!-- 
+    A section describing SMTP settings required by the script
+    -->
+    <SMTP>
+        <Server>smtpserver.com</Server>
+        <From>healthcheck@dummy.com</From>
+        <To>itadmins@dummy.com</To>
+        <UseSSL>True</UseSSL>
+        <RequireCredentials>False</RequireCredentials>
+        <UserName></UserName>
+        <EncryptedPassword></EncryptedPassword>
+    </SMTP>
+</Settings>

Examples/ConfigurationSample.ps1

@@ -0,0 +1,12 @@
+#
+# Sample script of using the PSScriptHelper module
+#
+# Generated by: Matticusau
+#
+# Generated on: 29/08/2017
+#
+
+Import-Module -Name C:\GitHub\PSScriptHelper
+
+Get-ScriptConfig -ScriptPath . -ScriptName 'ConfigurationSample' -ScriptVersion '1.0'
+

PSScriptHelper.psm1

@@ -0,0 +1,198 @@
+#
+# Module 'PSScriptHelper'
+#
+# Generated by: Matticusau
+#
+# Generated on: 29/08/2017
+#
+
+
+# setup the global variable for the scripts configuration if it doesn't exist
+if ($null -eq (Get-Variable -Name 'PSScriptHelperValues' -Scope Global -ErrorAction SilentlyContinue))
+{
+    [PSCustomObject]$Global:PSScriptHelperValues = @{
+        ScriptName = '';
+        ScriptPath = '';
+    }
+}
+
+
+
+
+
+##########################################################################################
+# Function: New-FolderPath
+#           Checks if the supplied path is either a fully qualified path or a sub-directory
+#           where in that case the supplied base folder or the script location is added
+#           also includes the option to create the folder if it doesn't exist
+##########################################################################################
+function New-FolderPath
+{
+    [CmdLetBinding(SupportsShouldProcess=$true)]
+    [OutputType([String])]
+    Param(
+        [Parameter(Mandatory=$true, HelpMessage='The folder path to validate/create')]
+        [string]$FolderPath
+        , 
+        [Parameter(Mandatory=$false, HelpMessage='The base folder to create the folder at. Defaults to current script path.')]
+        [string]$BaseFolder = ""
+        , 
+        [Parameter(Mandatory=$false, HelpMessage='If supplied the path will be created if it doesnt exist')]
+        [switch]$CreateFolder
+    )
+
+    try
+    {
+        [string]$newFolderPath = "";
+        #Write-Host "`$BaseFolder = $BaseFolder";
+        #set the base path depending on if we were provided one or to use the default
+        if ($BaseFolder.Length -eq 0) {$BaseFolder = $ScriptServerPath;} # Split-Path (Get-Variable MyInvocation -Scope 0).Value.MyCommand.Path
+        #Write-Host "`$BaseFolder = $BaseFolder";
+        #Write-Host "`$FolderPath = $FolderPath";
+
+        #check if we were given a path
+        if ($FolderPath.Length -gt 0) 
+        {
+            #check if we were given a UNC path or qualified path
+            if ($FolderPath.Substring(1,2) -eq ":\" -or $FolderPath.Substring(0,2) -eq "\\")
+            {
+                $newFolderPath = $FolderPath;
+            }
+            else
+            {
+                #we were given a sub folder
+                $newFolderPath = Join-Path -Path "$($BaseFolder)" -ChildPath "$($FolderPath)";
+            }
+            #Write-Host "`$newFolderPath = $newFolderPath";
+
+            #make sure this exists otherwise return nothing
+            if (!(Test-Path -Path $newFolderPath)) 
+            {
+                if ($CreateFolder = $true)
+                {
+                    if ($pscmdlet.ShouldProcess("$($newFolderPath)", "Create the folder path"))
+                    {
+                        New-Item $newFolderPath -ItemType Directory | Out-Null;
+                        #make sure we created it
+                        if (!(Test-Path -Path $newFolderPath)) {$newFolderPath = "";}
+                    }
+                }
+                else
+                {
+                    $newFolderPath = "";
+                }
+            }
+        }
+        else
+        {
+            $newFolderPath = "";
+        }
+
+    }
+    catch
+    {
+        #Tell the user something went wrong, we cannot log this to a file because we could be creating the log directory at the time
+        Write-Error -Message "Could not validate the path $($newFolderPath)." -Category ObjectNotFound;
+        $newFolderPath = "";
+    }
+    finally
+    {
+
+    }
+
+    #lastly return the data
+    return $newFolderPath;
+
+} # fn New-FolderPath
+
+
+
+
+
+
+
+##########################################################################################
+# Function: Get-ScriptConfig
+#           Gets the configuration for the current script
+##########################################################################################
+function Get-ScriptConfig
+{
+    [CmdLetBinding(SupportsShouldProcess=$true)]
+    Param(
+        [Parameter(Mandatory=$false, HelpMessage='The path to the script file to find a config for')]
+        [string]$ScriptPath=""
+        ,
+        [Parameter(Mandatory=$false, HelpMessage='The name of the script to retrieve config for')]
+        [string]$ScriptName=""
+        ,
+        [Parameter(Mandatory=$true, HelpMessage='The version of the script to validate the config with')]
+        [double]$ScriptVersion
+        ,
+        [Parameter(Mandatory=$false, HelpMessage='If supplied the config file will be created')]
+        [switch]$CreateFile
+    )
+
+    try
+    {
+        #set the variables if they were not supplied
+        if ($ScriptPath.Length -eq 0)
+        {
+            $ScriptPath = Split-Path (Get-Variable MyInvocation -Scope 0).Value.MyCommand.Path;
+        }
+        if ($ScriptName.Length -eq 0)
+        {
+            $ScriptName = $(Split-Path (Get-Variable MyInvocation -Scope 0).Value.MyCommand.Path -Leaf).Replace(".ps1","");
+        }
+
+        #the full path to script config file
+        [string]$configFilePath = "$($ScriptPath)\$($ScriptName).config"
+
+        #check that the file exists
+        if ((Test-Path -Path $configFilePath) -eq $false)
+        {
+            #file not found, should we create it
+            if ($CreateFile -eq $true)
+            {
+                if ($pscmdlet.ShouldProcess("$($configFilePath)", "Create the config file as it does not currently exist"))
+                {
+                    [xml]$TmpConfigFile = "<Settings ScriptName=`"`" Version=`"0`"><General></General></Settings>";
+                    $TmpConfigFile.Settings.ScriptName = "$($ScriptName)";
+                    $TmpConfigFile.Settings.Version = "$($ScriptVersion)";
+                    $TmpConfigFile.Save($configFilePath);
+                }
+            }
+            else
+            {
+                Write-Error -Message "The Script's Config file could not be found" -Category ObjectNotFound;
+                #Write-Host "Script is terminating";
+                Break;
+            }
+        }
+
+        #Create the object to hold the script file
+        [xml]$Script:Config = Get-Content "$($configFilePath)";
+
+        #check that this script file is valid
+        if ($Script:Config.Settings.ScriptName -ne $ScriptName)
+        {
+            Write-Error -Message "The Script's config file is invalid. Incorrect script name, expecting '$($ScriptName)'." -Category InvalidData;
+            Break;
+        }
+        if ($Script:Config.Settings.Version -lt $ScriptVersion)
+        {
+            Write-Error -Message "The Script's config file is invalid. Config file is for an older version of the script." -Category InvalidData;
+            Break;
+        }
+
+    }
+    catch
+    {
+        #Tell the user something went wrong
+        Write-Error -Message "Could not process the config file, exception was: $($_.Exception.Message)";
+    }
+    finally
+    {
+
+    }
+
+} # fn Get-ScriptConfig

README.md

@@ -1,2 +1,60 @@
-# PSScriptHelper
-A collections of cmdlets and functions that enhance scripts.
+# PowerShell Script Helper (PSScriptHelper)
+A collections of cmdlets and functions that enhance scripts. An example is the cmdlets to work with configuration data for a script.
+
+## System Requirements
+
+* WMF (PowerShell) 5.0
+
+## Required PowerShell Modules
+The following PowerShell modules.
+* Microsoft.PowerShell.Archive
+* ActiveDirectory
+* SqlServer
+
+## Example
+The following example demonstrates how to run this tool
+
+```
+Command goes here
+```
+
+## Versions
+This project uses [SemVer](http://semver.org/) for versioning. While the following is an overview of the offical releases, for the detailed versions available, see the [tags on this repository](https://github.com/your/project/tags). 
+
+### Unreleased
+
+* None
+
+### 1.0.0.0
+
+* Initial push 
+
+## I found a bug
+Create an issue through GitHub and lets work on solving it together :)
+
+## Contributing
+If you are interested in contributing please check out common DSC Resources [contributing guidelines](https://github.com/PowerShell/DscResource.Kit/blob/master/CONTRIBUTING.md). These are the standards I try and adopt for ALL of my work as well.
+
+### Dev Tools
+The following development tools have been used when authoring this project.
+* VSCode
+* VSCode Extensions - C#, , mssql, PowerShell, vscode-icons
+* PowerShell 5.0
+* Git
+
+### Setting up your Dev environment
+The following actions need to be taken if you wish to contribute
+1. Install VSCode
+2. Install PowerShell 5.0
+3. Install the VSCode Extensions - C#, mssql, PowerShell, vscode-icons
+4. Configure the extensions, for example set your icons (File > Preferences) to vscode-icons
+6. Clone this repository
+7. Create a branch for your work
+
+## License
+This project is released under the [GNU General Public License 3.0](https://github.com/Matticusau/.../blob/master/LICENSE)
+This project is released under the [MIT License](https://github.com/Matticusau/.../blob/master/LICENSE)
+
+## Contributors
+
+* Matticusau [GitHub](https://github.com/Matticusau) | [twitter](https://twitter.com/matticusau)