Merge pull request #4 from vNugglets/feat_AddFnForType

Add function for vSphere inventory object base types

Author: mtboren

ChangeLog.md

@@ -1,5 +1,9 @@
 ### ChangeLog for vNugglets.Utility PowerShell module
 
+#### v1.3, released 21 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-ThisModuleManifest.ps1

@@ -0,0 +1,55 @@
+<#	.Description
+	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(
+	## Module Version to set
+	[parameter(Mandatory=$true)][System.Version]$ModuleVersion,
+
+	## Recreate the manifest (overwrite with full, fresh copy instead of update?)
+	[Switch]$Recreate
+)
+begin {
+	$strModuleName = "vNugglets.Utility"
+	$strFilespecForPsd1 = Join-Path ($strModuleFolderFilespec = "$PSScriptRoot\$strModuleName") "${strModuleName}.psd1"
+
+	$hshManifestParams = @{
+		# Confirm = $true
+		Path = $strFilespecForPsd1
+		ModuleVersion = $ModuleVersion
+		Copyright = "MIT 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 "${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/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/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
+		# Verbose = $true
+	} ## end hashtable
+} ## end begin
+
+process {
+	$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
+		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_$strModuleName'", "# Module manifest for module '$strModuleName'") | Set-Content -Path $strFilespecForPsd1
+	} ## end if
+} ## end prcoess

Update-VNModuleManifest.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

testing/vNugglets.Utility.Tests_Unit.ps1

@@ -3,7 +3,7 @@
 #
 # Generated by: Matt Boren
 #
-# Generated on: 6/18/2017
+# Generated on: 1/19/2023
 #
 
 @{
@@ -12,7 +12,7 @@
 RootModule = 'vNuggletsUtilityMod.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.2.0'
+ModuleVersion = '1.3.0'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()
@@ -32,20 +32,20 @@ Copyright = 'MIT License'
 # Description of the functionality provided by this module
 Description = 'Module with the super useful functions that were previously scattered about the web by the vNugglets team (particularly, at vNugglets.com)'
 
-# Minimum version of the Windows PowerShell engine required by this module
-PowerShellVersion = '4.0'
+# Minimum version of the PowerShell engine required by this module
+PowerShellVersion = '5.0'
 
-# Name of the Windows PowerShell host required by this module
+# Name of the PowerShell host required by this module
 # PowerShellHostName = ''
 
-# Minimum version of the Windows PowerShell host required by this module
+# Minimum version of the PowerShell host required by this module
 # PowerShellHostVersion = ''
 
 # Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
 # DotNetFrameworkVersion = ''
 
 # Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
-# CLRVersion = ''
+# ClrVersion = ''
 
 # Processor architecture (None, X86, Amd64) required by this module
 # ProcessorArchitecture = ''
@@ -66,18 +66,19 @@ RequiredModules = @('VMware.VimAutomation.Core')
 # FormatsToProcess = @()
 
 # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
-NestedModules = @('vNuggletsUtilityMod_functions.ps1', 
+NestedModules = @('vNuggletsUtilityMod_functions.ps1',
                'vNugglets_SupportingFunctions.ps1')
 
 # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
-FunctionsToExport = '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', 
+FunctionsToExport = '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'
 
 # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
@@ -87,7 +88,7 @@ CmdletsToExport = @()
 # VariablesToExport = @()
 
 # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
-AliasesToExport = 'ConnVIServer', 'VNConnVIServer', 'DisconnVIServer', 
+AliasesToExport = 'ConnVIServer', 'VNConnVIServer', 'DisconnVIServer',
                'VNDisconnVIServer'
 
 # DSC resources to export from this module
@@ -97,9 +98,9 @@ AliasesToExport = 'ConnVIServer', 'VNConnVIServer', 'DisconnVIServer',
 # ModuleList = @()
 
 # List of all files packaged with this module
-FileList = 'vNugglets.Utility.psd1', 'vNuggletsUtilityMod.psm1', 
-               'vNuggletsUtilityMod_functions.ps1', 
-               'vNugglets_SupportingFunctions.ps1', 
+FileList = 'vNugglets.Utility.psd1', 'vNuggletsUtilityMod.psm1',
+               'vNuggletsUtilityMod_functions.ps1',
+               'vNugglets_SupportingFunctions.ps1',
                'en-US\about_vNugglets.Utility.help.txt'
 
 # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
@@ -111,7 +112,7 @@ PrivateData = @{
         Tags = 'vNugglets','vNugglets.com','VMware','vSphere','FaF','PowerCLI','VIRole','MAC','VM','RDM','vPG','VirtualPortgroup','EVC','VMHost','HBA','Datastore'
 
         # A URL to the license for this module.
-        LicenseUri = 'https://github.com/vNugglets/vNuggletsPSMod/blob/master/License'
+        LicenseUri = 'https://github.com/vNugglets/vNuggletsPSMod/blob/main/License'
 
         # A URL to the main website for this project.
         ProjectUri = 'https://github.com/vNugglets/vNuggletsPSMod'
@@ -120,13 +121,19 @@ PrivateData = @{
         IconUri = 'http://static.vnugglets.com/imgs/vNuggletsLogo.jpg'
 
         # ReleaseNotes of this module
-        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'
+
+        # Prerelease string of this module
+        # Prerelease = ''
+
+        # Flag to indicate whether the module requires explicit user acceptance for install/update/save
+        # RequireLicenseAcceptance = $false
 
         # External dependent modules of this module
-        # ExternalModuleDependencies = ''
+        # ExternalModuleDependencies = @()
 
     } # End of PSData hashtable
-    
+
  } # End of PrivateData hashtable
 
 # HelpInfo URI of this module