Merge branch 'dev'

Author: mtboren

ChangeLog.md

@@ -1,5 +1,19 @@
 ### ChangeLog for vNugglets.Utility PowerShell module
 
+#### v1.2, released 18 Jun 2017
+
+- \[improvement] updated function `Get-VNVMByAddress`:
+  - greatly increased speed by using `VMware.Vim.SearchIndex` for by-IP searches (`SearchIndex` search methods do not support wildcard, though, so getting VM by wildcard address still uses slower mechanism); example speed increase for searching for VM by specific IP: went from 13s to about 0.25s in a vCenter with about 7,500 VMs -- woo-hoo!
+  - added new parameters `-GuestHostname` and `-UUID` to support for searching by guest DNS name or VM BIOS UUID, respectively (these also use methods of `VMware.Vim.SearchIndex` object, so the searches are super fast)
+- \[improvement] updated function `Copy-VNVIRole`:
+  - takes new parameter, `-SourceRole`, for passing VIRole object itself as value, and this parameter accepts value from pipeline, for more natural use of cmdlet
+  - deduces source vCenter server from `-SourceRole` value, simplifying use of cmdlet (no need to specify `-SourceVCName` parameter when providing the source VIRole object)
+  - `-DestinationVCName` parameter now optional, further simplifying use of cmdlet; if parameter not specified, destination vCenter will be the same as the source vCenter
+- \[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
 
 - \[new] added function `Find-VNVMWithDuplicateMACAddress` for finding duplicate VM NIC MAC address in vCenter
@@ -10,13 +24,13 @@
 - created module from many of the juicy snippets/functions that we shared at [vNugglets.com](http://vNugglets.com) over the years
 - updated `Copy-VNVIRole` to be a safer function overall by removing old `Invoke-Expression` methodology
 - standardized parameter names across cmdlets in the module and expanded some previously truncated/cryptic parameter names (go, usability and discoverability!)
-- added/updated "by name regular expression pattern" and "by liternal name string" parameters to several cmdlets
+- added/updated "by name regular expression pattern" and "by literal name string" parameters to several cmdlets
 - modernized cmdlets to use capabilities of somewhat newer PowerShell releases (like ordered hashtables) and built-in property return iteration, breaking PowerShell v2.0 compatibility (it's time to upgrade, right?)
-- updated `Invoke-VNEvacuateDatastore`:  
+- updated `Invoke-VNEvacuateDatastore`:
   - added feature that uses any/all datastores in datastore cluster (when specifying a datastore cluster for Destination parameter value) for potential destination _per object_ (this allows for a potentially different datastore for each virtual disk on a VM)
   - added ability to exclude a VM/template's files from evacuation process (via parameter)
   - added `-WhatIf` support
-- updated cmdlet names to use standard/approved verbs where they were not already in use. Renamed functions/snippets as follows:  
+- updated cmdlet names to use standard/approved verbs where they were not already in use. Renamed functions/snippets as follows:
   - `Get-VNVMByRDM` was "Get-VMWithGivenRDM"
   - `Get-VNVMByVirtualPortGroup` was "Get-VMOnNetworkPortGroup"
   - `Get-VNVMHostBrokenUplink` was "Get-BustedVmnic"

License

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016 vNugglets
+Copyright (c) since 2016, vNugglets
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

ToDo.md

@@ -5,11 +5,7 @@
   - support for virtual distributed switches ("vDS" or "vDSwitches"); currently only supports virtual standard switches ("vSS")
   - support for accepting VMHost ID from pipeline (by property), so that the following works tip top:  
   `Get-Cluster myCluster | Get-VMHost | Get-VNVMHostBrokenUplink`
-- update function `Get-VNVMByAddress` to:
-  - use `VMware.Vim.SearchIndex` for speed for FindAllByIp (does support wildcard, though)
-  - support searching by guest DNS name (also using `VMware.Vim.SearchIndex`, via the `FindAllByDnsName` method)
 - update function `Get-VNVMByVirtualPortGroup` to take a standard- or distributed virtual portgroup as a parameter (and, from pipeline)
-- update function `Copy-VNVIRole` to take SourceVIRole as VIRole object, and to accept it from pipeline
 - update function `Get-VNUplinkNicForVM` to give more meaningful VDSwitch identification (currently returns something to the effect of `DvsPortset-1` for the VDSwitch name)
 - ?add function for changing VM boot order
 - investigate using a PropertyCollector to more quickly retrieve VM network adapter MAC addresses for function `Find-VNVMWithDuplicateMACAddress`

Update-VNModuleManifest.ps1

@@ -0,0 +1,72 @@
+<#	.Description
+	Some code to help automate the updating of the ModuleManifest file
+#>
+[CmdletBinding(SupportsShouldProcess=$true)]
+param()
+begin {
+	## some code to generate the module manifest
+	$strFilespecForPsd1 = "$PSScriptRoot\vNugglets.Utility\vNugglets.Utility.psd1"
+
+	$hshModManifestParams = @{
+		# Confirm = $true
+		Path = $strFilespecForPsd1
+		ModuleVersion = "1.2.0"
+		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
+		IconUri = "http://static.vnugglets.com/imgs/vNuggletsLogo.jpg"
+		LicenseUri = "https://github.com/vNugglets/vNuggletsPSMod/blob/master/License"
+		NestedModules = Write-Output vNuggletsUtilityMod_functions.ps1 vNugglets_SupportingFunctions.ps1
+		# PassThru = $true
+		ProjectUri = "https://github.com/vNugglets/vNuggletsPSMod"
+		ReleaseNotes = "See release notes at https://github.com/vNugglets/vNuggletsPSMod/blob/master/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 Address" VM RDM vPG "Virtual Portgroup" EVC VMHost HBA Datastore
+		# Verbose = $true
+	} ## end hashtable
+} ## end begin
+
+process {
+	if ($PsCmdlet.ShouldProcess($strFilespecForPsd1, "Update module manifest")) {
+		## do the actual module manifest update
+		PowerShellGet\Update-ModuleManifest @hshModManifestParams
+		## 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
+	} ## 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
+#>

makeModule.ps1

@@ -3,7 +3,7 @@
 #
 # Generated by: Matt Boren
 #
-# Generated on: 12/6/2016
+# Generated on: 6/18/2017
 #
 
 @{
@@ -12,7 +12,10 @@
 RootModule = 'vNuggletsUtilityMod.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.1.0'
+ModuleVersion = '1.2.0'
+
+# Supported PSEditions
+# CompatiblePSEditions = @()
 
 # ID used to uniquely identify this module
 GUID = 'a22ca8fe-3739-463f-b8dd-4d5d2c9ffec4'
@@ -27,7 +30,7 @@ CompanyName = 'vNugglets.com'
 Copyright = 'MIT License'
 
 # Description of the functionality provided by this module
-Description = 'Module with the functions that have previously been scattered about the web by the vNugglets team (particularly, at vNugglets.com'
+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'
@@ -38,17 +41,17 @@ PowerShellVersion = '4.0'
 # Minimum version of the Windows PowerShell host required by this module
 # PowerShellHostVersion = ''
 
-# Minimum version of Microsoft .NET Framework required by this module
+# 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
+# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
 # CLRVersion = ''
 
 # Processor architecture (None, X86, Amd64) required by this module
 # ProcessorArchitecture = ''
 
 # Modules that must be imported into the global environment prior to importing this module
-# RequiredModules = @()
+RequiredModules = @('VMware.VimAutomation.Core')
 
 # Assemblies that must be loaded prior to importing this module
 # RequiredAssemblies = @()
@@ -66,17 +69,29 @@ PowerShellVersion = '4.0'
 NestedModules = @('vNuggletsUtilityMod_functions.ps1', 
                'vNugglets_SupportingFunctions.ps1')
 
-# Functions to export from this module
-FunctionsToExport = '*'
+# 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', 
+               'Update-VNTitleBarForPowerCLI'
 
-# Cmdlets to export from this module
-# CmdletsToExport = @()
+# 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.
+CmdletsToExport = @()
 
 # Variables to export from this module
 # VariablesToExport = @()
 
-# Aliases to export from this module
-# AliasesToExport = @()
+# 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', 
+               'VNDisconnVIServer'
+
+# DSC resources to export from this module
+# DscResourcesToExport = @()
 
 # List of all modules packaged with this module
 # ModuleList = @()
@@ -85,10 +100,34 @@ FunctionsToExport = '*'
 FileList = 'vNugglets.Utility.psd1', 'vNuggletsUtilityMod.psm1', 
                'vNuggletsUtilityMod_functions.ps1', 
                'vNugglets_SupportingFunctions.ps1', 
-               'about_vNugglets.Utility.help.txt'
+               '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.
+PrivateData = @{
+
+    PSData = @{
+
+        # Tags applied to this module. These help with module discovery in online galleries.
+        Tags = 'vNugglets','vNugglets.com','VMware vSphere','FaF','PowerCLI','VIRole','MAC Address','VM','RDM','vPG','Virtual Portgroup','EVC','VMHost','HBA','Datastore'
+
+        # A URL to the license for this module.
+        LicenseUri = 'https://github.com/vNugglets/vNuggletsPSMod/blob/master/License'
+
+        # A URL to the main website for this project.
+        ProjectUri = 'https://github.com/vNugglets/vNuggletsPSMod'
+
+        # A URL to an icon representing this module.
+        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'
+
+        # External dependent modules of this module
+        # ExternalModuleDependencies = ''
 
-# Private data to pass to the module specified in RootModule/ModuleToProcess
-# PrivateData = ''
+    } # End of PSData hashtable
+    
+ } # End of PrivateData hashtable
 
 # HelpInfo URI of this module
 # HelpInfoURI = ''

vNugglets.Utility/vNugglets.Utility.psd1

@@ -1,6 +1,3 @@
-## dot-source the config items file
-#. $PSScriptRoot\configItems.ps1
-
 ## Set aliases; when setting value for DefaultCommandPrefix in module, need to account for that when setting value for Alias here (value needs to be of what the final function name will be with that DefaultCommandPrefix)
 $hshNewAliasInfo = @{
 	## Connect and Disconnect VIServer
@@ -13,14 +10,11 @@ $arrAliasNamesToExport = $hshNewAliasInfo.GetEnumerator() | Foreach-Object {
 	$strNameThisAlias,"VN$strNameThisAlias" | Foreach-Object {if (-not (Get-Alias -Name $_ -ErrorAction:SilentlyContinue)) {New-Alias -Name $_ -Value $strValueThisAlias; $_}}
 } ## end foreach-object
 
-## export these items for use by consumer
-$hshModuleMemberParams = @{
-	Function = 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
-	Alias = $arrAliasNamesToExport
-} ## end hsh
+## now handled in module manifest
+# ## export these items for use by consumer
+# $hshModuleMemberParams = @{
+# 	Alias = $arrAliasNamesToExport
+# } ## end hsh
 
-## do the actual member export
-Export-ModuleMember @hshModuleMemberParams
+# ## do the actual member export
+# Export-ModuleMember @hshModuleMemberParams