Prep for fn add, update the Update script

Author: mtboren

ChangeLog.md

@@ -1,5 +1,9 @@
 ### ChangeLog for vNugglets.Utility PowerShell module
 
+#### v1.3, released Jan 2023
+
+- \[new] added function `Get-VNInventoryType` for getting more future-safer vSphere object types (follwing guidance from VMware)
+
 #### v1.2, released 18 Jun 2017
 
 - \[improvement] updated function `Get-VNVMByAddress`:
@@ -12,7 +16,7 @@
 - \[internal improvement] updated module prepartion to use `Update-ModuleManifest` for keeping module manifest in shape
   - added manifest entries for tags and for URIs for project, release notes, license, etc.
   - prepared for publishing to the [PowerShellGallery](https://www.powershellgallery.com/))
-  
+
 
 #### v1.1, released 20 Dec 2016
 

ReadMe.md

@@ -18,6 +18,7 @@ Some of the functionality provided by the cmdlets in this module:
 - vCenter connection information (in title of PowerShell window)
 - Datastore evacuation, template evacuation from VMHosts
 - Mining virtual portgroup information (cluster-locations)
+- Determining parent/base vSphere object types for use in parameter type-ing in subsequent function development
 
 <a id="quickStart"></a>
 ### QuickStart
@@ -45,7 +46,7 @@ The [ChangeLog](ChangeLog.md) for this module is, of course, a log of the major
 - download the module, either from the latest release's .zip file on the [vNugglets.Utility Releases](https://github.com/vNugglets/vNuggletsPSMod/releases) page, or by cloning the project to some local folder with Git via:
   `PS C:\> git clone https://github.com/vNugglets/vNuggletsPSMod.git C:\temp\MyVNuggsRepoCopy`
 - put the actual PowerShell module directory in some place that you like to keep your modules, say, like this, which copies the module to your personal Modules directory:
-  `PS C:\> Copy-Item -Recurse -Path C:\temp\MyVNuggsRepoCopy\vNugglets.Utility\ -Destination ~\Documents\WindowsPowerShell\Modules\vNugglets.Utility`
+  `PS C:\> Copy-Item -Recurse -Path C:\temp\MyVNuggsRepoCopy\vNugglets.Utility\ -Destination ~\Documents\PowerShell\Modules\vNugglets.Utility`
 - import the PowerShell module into the current PowerShell session:
   `PS C:\> Import-Module -Name vNugglets.Utility`
   or, if the vNugglets.Utility module folder is not in your `Env:\PSModulePath`, specify the whole path to the module folder, like:

Update-VNModuleManifest.ps1

@@ -1,27 +1,36 @@
 <#	.Description
-	Some code to help automate the updating of the ModuleManifest file
+	Some code to help automate the updating of the ModuleManifest file (will create it if it does not yet exist, too)
 #>
 [CmdletBinding(SupportsShouldProcess=$true)]
-param()
+param(
+	## Module Version to set
+	[parameter(Mandatory=$true)][System.Version]$ModuleVersion,
+
+	## Recreate the manifest (overwrite with full, fresh copy instead of update?)
+	[Switch]$Recreate
+)
 begin {
-	## some code to generate the module manifest
-	$strFilespecForPsd1 = "$PSScriptRoot\vNugglets.Utility\vNugglets.Utility.psd1"
+	$strModuleName = "vNugglets.Utility"
+	$strFilespecForPsd1 = Join-Path ($strModuleFolderFilespec = "$PSScriptRoot\$strModuleName") "${strModuleName}.psd1"
 
-	$hshModManifestParams = @{
+	$hshManifestParams = @{
 		# Confirm = $true
 		Path = $strFilespecForPsd1
-		ModuleVersion = "1.2.0"
+		ModuleVersion = $ModuleVersion
+		Copyright = "Apache 2.0 License"
 		Description = "Module with the super useful functions that were previously scattered about the web by the vNugglets team (particularly, at vNugglets.com)"
 		## some aliases, both as written, and with "VN" prefixed on them
 		AliasesToExport = Write-Output ConnVIServer DisconnVIServer | Foreach-Object {$_; "VN$_"}
-		FileList = Write-Output vNugglets.Utility.psd1 vNuggletsUtilityMod.psm1 vNuggletsUtilityMod_functions.ps1, vNugglets_SupportingFunctions.ps1, en-US\about_vNugglets.Utility.help.txt
-		FunctionsToExport = Write-Output Connect-VNVIServer Copy-VNVIRole Disconnect-VNVIServer Find-VNVMWithDuplicateMACAddress Get-VNNetworkClusterInfo Get-VNUplinkNicForVM Get-VNVMByAddress Get-VNVMByRDM Get-VNVMByVirtualPortGroup Get-VNVMDiskAndRDM Get-VNVMEVCInfo Get-VNVMHostBrokenUplink Get-VNVMHostFirmwareInfo Get-VNVMHostHBAWWN Get-VNVMHostLogicalVolumeInfo Get-VNVMHostNICFirmwareAndDriverInfo Invoke-VNEvacuateDatastore Move-VNTemplateFromVMHost Update-VNTitleBarForPowerCLI
+		FileList = Write-Output "${strModuleName}.psd1" vNuggletsUtilityMod.psm1 vNuggletsUtilityMod_functions.ps1 vNugglets_SupportingFunctions.ps1 "en-US\about_${strModuleName}.help.txt"
+		FunctionsToExport = Write-Output Connect-VNVIServer Copy-VNVIRole Disconnect-VNVIServer Find-VNVMWithDuplicateMACAddress Get-VNInventoryType Get-VNNetworkClusterInfo Get-VNUplinkNicForVM Get-VNVMByAddress Get-VNVMByRDM Get-VNVMByVirtualPortGroup Get-VNVMDiskAndRDM Get-VNVMEVCInfo Get-VNVMHostBrokenUplink Get-VNVMHostFirmwareInfo Get-VNVMHostHBAWWN Get-VNVMHostLogicalVolumeInfo Get-VNVMHostNICFirmwareAndDriverInfo Invoke-VNEvacuateDatastore Move-VNTemplateFromVMHost Update-VNTitleBarForPowerCLI
 		IconUri = "http://static.vnugglets.com/imgs/vNuggletsLogo.jpg"
-		LicenseUri = "https://github.com/vNugglets/vNuggletsPSMod/blob/master/License"
+		LicenseUri = "https://github.com/vNugglets/vNuggletsPSMod/blob/main/License"
+		## scripts (.ps1) that are listed in the NestedModules key are run in the module's session state, not in the caller's session state. To run a script in the caller's session state, list the script file name in the value of the ScriptsToProcess key in the manifest; RegisterArgCompleter apparently needs to be added _after_ function definition .ps1 files are run (via NestedModules) (else, given functions are not defined, and if RegisterArgCompleter is referring to commands from module dynamically, it would not get them; that is the case if the function definitions are in a .psm1 file instead of .ps1 file, and are being defined in NestedModules)
 		NestedModules = Write-Output vNuggletsUtilityMod_functions.ps1 vNugglets_SupportingFunctions.ps1
 		# PassThru = $true
+		PowerShellVersion = [System.Version]"5.0"
 		ProjectUri = "https://github.com/vNugglets/vNuggletsPSMod"
-		ReleaseNotes = "See release notes at https://github.com/vNugglets/vNuggletsPSMod/blob/master/ChangeLog.md"
+		ReleaseNotes = "See release notes at https://github.com/vNugglets/vNuggletsPSMod/blob/main/ChangeLog.md"
 		## relies on a centrally-important VMware PowerCLI module
 		RequiredModules = "VMware.VimAutomation.Core"
 		Tags = Write-Output vNugglets vNugglets.com VMware vSphere FaF PowerCLI VIRole MAC VM RDM vPG VirtualPortgroup EVC VMHost HBA Datastore
@@ -30,43 +39,17 @@ begin {
 } ## end begin
 
 process {
-	if ($PsCmdlet.ShouldProcess($strFilespecForPsd1, "Update module manifest")) {
+	$bManifestFileAlreadyExists = Test-Path $strFilespecForPsd1
+	## check that the FileList property holds the names of all of the files in the module directory, relative to the module directory
+	## the relative names of the files in the module directory (just filename for those in module directory, "subdir\filename.txt" for a file in a subdir, etc.)
+	$arrRelativeNameOfFilesInModuleDirectory = Get-ChildItem $strModuleFolderFilespec -Recurse | Where-Object {-not $_.PSIsContainer} | ForEach-Object {$_.FullName.Replace($strModuleFolderFilespec, "", [System.StringComparison]::OrdinalIgnoreCase).TrimStart("\")}
+	if ($arrDiffResults = (Compare-Object -ReferenceObject $hshManifestParams.FileList -DifferenceObject $arrRelativeNameOfFilesInModuleDirectory)) {Write-Error "Uh-oh -- FileList property value for making/updating module manifest and actual files present in module directory do not match. Better check that. The variance:`n$($arrDiffResults | Out-String)"} else {Write-Verbose -Verbose "Hurray, all of the files in the module directory are named in the FileList property to use for the module manifest"}
+	$strMsgForShouldProcess = "{0} module manifest" -f $(if ((-not $bManifestFileAlreadyExists) -or $Recreate) {"Create"} else {"Update"})
+	if ($PsCmdlet.ShouldProcess($strFilespecForPsd1, $strMsgForShouldProcess)) {
 		## do the actual module manifest update
-		PowerShellGet\Update-ModuleManifest @hshModManifestParams
+		if ((-not $bManifestFileAlreadyExists) -or $Recreate) {Microsoft.PowerShell.Core\New-ModuleManifest @hshManifestParams}
+		else {PowerShellGet\Update-ModuleManifest @hshManifestParams}
 		## replace the comment in the resulting module manifest that includes "PSGet_" prefixed to the actual module name with a line without "PSGet_" in it
-		(Get-Content -Path $strFilespecForPsd1 -Raw).Replace("# Module manifest for module 'PSGet_vNugglets.Utility'", "# Module manifest for module 'vNugglets.Utility'") | Set-Content -Path $strFilespecForPsd1
+		(Get-Content -Path $strFilespecForPsd1 -Raw).Replace("# Module manifest for module 'PSGet_$strModuleName'", "# Module manifest for module '$strModuleName'") | Set-Content -Path $strFilespecForPsd1
 	} ## end if
 } ## end prcoess
-
-
-<#
-## used for original manifest creation
-$hshModManifestParams = @{
-	Path = $strFilespecForPsd1
-	Author = "Matt Boren"
-	CompanyName = "vNugglets.com"
-	Copyright = "MIT License"
-	## when setting value for DefaultCommandPrefix in module, need to account for that when setting value for Aliases anywhere (need to code those to point at what the functions _will_ be called when the DefaultCommandPrefix is applied)
-	#DefaultCommandPrefix = ""
-	#FormatsToProcess = "SomeModule.format.ps1xml"
-	ModuleToProcess = "vNuggletsUtilityMod.psm1"
-	ModuleVersion = "1.1.0"
-	## scripts (.ps1) that are listed in the NestedModules key are run in the module's session state, not in the caller's session state. To run a script in the caller's session state, list the script file name in the value of the ScriptsToProcess key in the manifest
-	NestedModules = @("vNuggletsUtilityMod_functions.ps1", "vNugglets_SupportingFunctions.ps1")
-	PowerShellVersion = [System.Version]"4.0"
-	Description = "Module with the functions that have previously been scattered about the web by the vNugglets team (particularly, at vNugglets.com"
-	## specifies script (.ps1) files that run in the caller's session state when the module is imported. You can use these scripts to prepare an environment, just as you might use a login script
-	# ScriptsToProcess = "New-HtmlReport_configItems.ps1"
-	VariablesToExport = @()
-	AliasesToExport = @()
-	CmdletsToExport = @()
-	FileList = Write-Output vNugglets.Utility.psd1 vNuggletsUtilityMod.psm1 vNuggletsUtilityMod_functions.ps1, vNugglets_SupportingFunctions.ps1, about_vNugglets.Utility.help.txt
-	Verbose = $true
-}
-## using -PassThru so as to pass the generated module manifest contents to a var for later output as ASCII (instead of having a .psd1 file of default encoding, Unicode)
-$oManifestOutput = New-ModuleManifest @hshModManifestParams -PassThru
-## have to do in separate step, as PSD1 file is "being used by another process" -- the New-ModuleManifest cmdlet, it seems
-#   in order to have this module usable (importable) via PowerShell v2, need to update the newly created .psd1 file, replacing the 'RootModule' keyword with 'ModuleToProcess'
-# ($oManifestOutput -split "`n" | Foreach-Object {$_ -replace "^RootModule = ", "ModuleToProcess = "}) -join "`n" | Out-File -Verbose -FilePath $strFilespecForPsd1 -Encoding ASCII
-$oManifestOutput | Out-File -Verbose $strFilespecForPsd1 -Encoding ASCII
-#>

testing/vNugglets.Utility.Tests_Unit.ps1

@@ -9,23 +9,6 @@
 
 Write-Verbose -Verbose "tests not yet fully written"
 
-<#
-Cmdlets for which to still write tests:
-Copy-VNVIRole
-Disconnect-VNVIServer
-Get-VNNetworkClusterInfo
-Get-VNUplinkNicForVM
-Get-VNVMByAddress
-Get-VNVMByRDM
-Get-VNVMByVirtualPortGroup
-Get-VNVMDiskAndRDM
-Get-VNVMEVCInfo
-Get-VNVMHostBrokenUplink
-Invoke-VNEvacuateDatastore
-Move-VNTemplateFromVMHost
-Update-VNTitleBarForPowerCLI
-#>
-
 $oTestVMHost = Get-VMHost -State Connected | Select-Object -First 1
 
 ## array of objects, each with information about what and how to test for the given cmdlet; used to create, for each cmdlet, the actual tests below