Merge pull request #42 from AsBuiltReport/dev

v1.3.0 release

Author: tpcarman

.github/ISSUE_TEMPLATE/bug_report.md

@@ -21,11 +21,9 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **System (please provide the following information about the system from which you are trying to generate a report):**
- - OS: [e.g. Windows 10]
- - Windows PowerShell version [Provide output from the following command: `$PSVersionTable.PSVersion`]
- - Vendor PowerShell Module name and version [e.g. VMware PowerCLI 11.2]
- - AsBuiltReport.Core module version [e.g. 1.0.0]
- - AsBuiltReport module name and version [e.g. AsBuiltReport.VMware.vSphere 1.0.0]
+ - Operating System: [e.g. Windows 10, macOS 12, Ubuntu 20.04]
+ - PowerShell version [Provide output from the following command: `$PSVersionTable`]
+ - AsBuiltReport.Core module version [Provide output from the following command: `Get-Module -ListAvailable AsBuiltReport.Core`]
 
 **Additional context**
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -5,7 +5,7 @@ about: Suggest an idea for this project
 ---
 
 **Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+A clear and concise description of what the problem is. e.g. I'm always frustrated when [...]
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.

.github/PULL_REQUEST_TEMPLATE.md

@@ -31,4 +31,4 @@
 - [ ] My code follows the code style of this project.
 - [ ] My change requires a change to the documentation.
 - [ ] I have updated the documentation accordingly.
-- [ ] I have read the [**CONTRIBUTING**](/CONTRIBUTING.md) document.
+- [ ] I have read the [**CONTRIBUTING**](/CONTRIBUTING.md) page.

.github/workflows/PSScriptAnalyzerSettings.psd1

@@ -3,6 +3,8 @@
         'PSUseToExportFieldsInManifest',
         'PSReviewUnusedParameter',
         'PSUseDeclaredVarsMoreThanAssignments',
-        'PSAvoidGlobalVars'
+        'PSAvoidGlobalVars',
+        'PSAvoidUsingConvertToSecureStringWithPlainText',
+        'PSAvoidUsingUsernameAndPasswordParams'
     )
 }

.github/workflows/Release.yml

@@ -17,11 +17,16 @@ jobs:
         shell: pwsh
         run: |
           Install-Module -Name PScribo -Repository PSGallery -Force
+      - name: Test Module Manifest
+        shell: pwsh
+        run: |
+          Test-ModuleManifest .\AsBuiltReport.Core.psd1
       - name: Publish module to PowerShell Gallery
         shell: pwsh
         run: |
           Publish-Module -Path ./ -NuGetApiKey ${{ secrets.PSGALLERY_API_KEY }} -Verbose
   tweet:
+    needs: publish-to-gallery
     runs-on: ubuntu-latest
     steps:
       - uses: Eomm/why-don-t-you-tweet@v1

AsBuiltReport.Core.psd1

@@ -13,7 +13,7 @@
 
     # Version number of this module.
 
-    ModuleVersion = '1.2.0'
+    ModuleVersion = '1.3.0'
 
     # Supported PSEditions
     # CompatiblePSEditions = 'Desktop'
@@ -28,13 +28,13 @@
     # CompanyName = ''
 
     # Copyright statement for this module
-    Copyright = '(c) 2020 Tim Carman. All rights reserved.'
+    Copyright = '(c) 2022 Tim Carman. All rights reserved.'
 
     # Description of the functionality provided by this module
     Description = 'A PowerShell module which provides the core framework for generating As-Built documentation for many common datacentre systems.'
 
     # Minimum version of the Windows PowerShell engine required by this module
-    PowerShellVersion = '5.1'
+    # PowerShellVersion = '5.1'
 
     # Name of the Windows PowerShell host required by this module
     # PowerShellHostName = ''
@@ -55,7 +55,7 @@
     RequiredModules = @(
         @{
             ModuleName = 'PScribo';
-            ModuleVersion = '0.9.1'
+            ModuleVersion = '0.10.0'
         }
     )
 

CHANGELOG.md

@@ -1,4 +1,17 @@
-# :arrows_counterclockwise: AsBuiltReport.Core Changelog
+# :arrows_clockwise: AsBuiltReport.Core Changelog
+
+## [1.3.0] - 2022-10-22
+
+### Added
+- Added two sample style scripts
+### Changed
+- Updated `RequiredModules` for PScribo 0.10.0
+- Updated installation instructions in `README.md`
+- Updated contributing guide in `CONTRIBUTING.md`
+- Updated PSScriptAnalyzer settings
+- Updated GitHub issue templates
+- Updated comment based help for AsBuiltReport cmdlets
+- Improved command functionality for macOS and Linux users
 
 ## [1.2.0] - 2022-02-11
 ### Added

CONTRIBUTING.md

@@ -23,6 +23,10 @@
             <img src="https://img.shields.io/twitter/follow/AsBuiltReport.svg?style=social"/></a>
 </p>
 
+<p align="center">
+    <a href='https://ko-fi.com/B0B7DDGZ7' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
+</p>
+
 # AsBuiltReport.Core
 
 AsBuiltReport.Core is a PowerShell module which provides the core framework for generating as built documentation for many common datacentre systems. The AsBuiltReport.Core module is required by each individual report module used to generate as built documentation for a specific product and/or technology.
@@ -33,21 +37,21 @@ The following simple list of instructions will get you started with the AsBuiltR
 
 ## :floppy_disk: Supported Versions
 ### **PowerShell**
-This report is compatible with the following PowerShell versions;
+This module is compatible with the following PowerShell versions;
 
 | Windows PowerShell 5.1 | PowerShell 7 |
 |:----------------------:|:------------------:|
 |   :white_check_mark:   | :white_check_mark: |
 
 ## :wrench: System Requirements
 
-The following module will be automatically installed by following the [module installation](https://github.com/AsBuiltReport/AsBuiltReport.Core#package-module-installation) procedure.
+The following PowerShell module will be automatically installed by following the [module installation](https://github.com/AsBuiltReport/AsBuiltReport.Core#package-module-installation) procedure.
 
-This module may also be manually installed.
+This PowerShell module may also be manually installed via the PowerShell Gallery or GitHub.
 
 | Module Name        | Minimum Required Version |                          PS Gallery                           |                                   GitHub                                    |
 |--------------------|:------------------------:|:---------------------------------------------------------------------:|:---------------------------------------------------------------------------:|
-| PScribo            |          0.9.1           |      [Link](https://www.powershellgallery.com/packages/PScribo)       |         [Link](https://github.com/iainbrighton/PScribo/tree/master)
+| PScribo            |          0.10.0           |      [Link](https://www.powershellgallery.com/packages/PScribo)       |         [Link](https://github.com/iainbrighton/PScribo/tree/master)
 
 To find a list of available report modules, run the following PowerShell command;
 
@@ -59,19 +63,53 @@ The pre-requisites for each report type will be documented within its own `READM
 
 ## :package: Module Installation
 
-### **PowerShell**
-Open a PowerShell terminal window and install the required module as follows;
+### PowerShell
+#### Online Installation
+
+For an online installation, install the `AsBuiltReport.Core` module using the [PowerShell Gallery](https://www.powershellgallery.com/packages?q=Asbuiltreport.Core);
+
+```powershell
+# Install AsBuiltReport module
+Install-Module -Name 'AsBuiltReport.Core' -Repository 'PSGallery' -Scope 'CurrentUser'
+```
+
+#### Offline Installation
+
+For an offline installation, perform the following steps from a machine with internet connectivity;
+
+Save the required `AsBuiltReport.Core` module to a specified folder.
+
 ```powershell
-install-module AsBuiltReport.Core
+# Save AsBuiltReport.Core module
+Save-Module -Name 'AsBuiltReport.Core' -Repository 'PSGallery' -Path '<Folder Path>'
 ```
 
+Copy the downloaded `AsBuiltReport.Core` module folder to a location that can be made accessible to the offline system.
+e.g. USB Flash Drive, Internal File Share etc.
+
+On the offline system, open a PowerShell console window and run the following command to determine the PowerShell module path.
+
+**Windows**
+
+```powershell title=""
+$env:PSModulePath -Split ';'
+```
+
+**macOS & Linux**
+
+```powershell title=""
+$env:PSModulePath -Split ':'
+```
+
+Copy the downloaded `AsBuiltReport.Core` module folder to a folder specified in the `$env:PSModulePath` output.
+
 ### **GitHub**
-If you are unable to use the PowerShell Gallery, you can still install the module manually. Ensure you repeat the following steps for the [system requirements](https://github.com/AsBuiltReport/AsBuiltReport.Core#wrench-system-requirements) also.
+If you are unable to use the PowerShell Gallery, you can still install the `AsBuiltReport.Core` module manually. Ensure you repeat the following steps for the [system requirements](https://github.com/AsBuiltReport/AsBuiltReport.Core#wrench-system-requirements) also.
 
 1. Download the [latest release](https://github.com/AsBuiltReport/AsBuiltReport.Core/releases/latest) zip from GitHub
 2. Extract the zip file
-3. Copy the folder `AsBuiltReport.Core` to a path that is set in `$env:PSModulePath`. By default this could be `C:\Program Files\WindowsPowerShell\Modules` or `C:\Users\<user>\Documents\WindowsPowerShell\Modules`
-4. Open a PowerShell terminal window and unblock the downloaded files with
+3. Copy the folder `AsBuiltReport.Core` to a path that is set in `$env:PSModulePath`.
+4. For Windows users only, open a PowerShell terminal window and unblock the downloaded files with
     ```powershell
     $path = (Get-Module -Name AsBuiltReport.Core -ListAvailable).ModuleBase; Unblock-File -Path $path\*.psd1; Unblock-File -Path $path\Src\Public\*.ps1
     ```
@@ -158,11 +196,13 @@ The `New-AsBuiltReportConfig` cmdlet is used to create JSON configuration files
 .PARAMETER Force
     Specifies to overwrite any existing report JSON configuration file
 .EXAMPLE
-    Creates a report JSON configuration file for VMware vSphere, named 'vSphere_Report_Config' in 'C:\Reports' folder.
     New-AsBuiltReportConfig -Report VMware.vSphere -FolderPath 'C:\Reports' -Filename 'vSphere_Report_Config'
+
+    Creates a VMware vSphere report configuration file named 'vSphere_Report_Config.json' in the 'C:\Reports' folder.
 .EXAMPLE
-    Creates a report JSON configuration file for Nutanix Prism Central, named 'AsBuiltReport.Nutanix.PrismCentral' in 'C:\Reports' folder, overwriting any existing file.
-    New-AsBuiltReportConfig -Report Nutanix.PrismCentral -FolderPath 'C:\Reports' -Force
+    New-AsBuiltReportConfig -Report Nutanix.PrismElement -FolderPath '/Users/Tim/Reports' -Force
+
+    Creates a Nutanix Prism Element report configuration file name 'AsBuiltReport.Nutanix.PrismElement.json' in '/Users/Tim/Reports' folder and overwrites the existing file.
 ```
 
 ```powershell
@@ -173,36 +213,38 @@ Get-Help New-AsBuiltReportConfig -Full
 Here are some examples to get you going.
 
 ```powershell
-# The following creates a VMware vSphere As Built report in HTML & Word formats.
-# The document will highlight particular issues which exist within the environment by including the Healthchecks switch.
-PS C:\>New-AsBuiltReport -Report VMware.vSphere -Target 192.168.1.100 -Username admin -Password admin -Format HTML,Word -EnableHealthCheck -OutputFolderPath 'H:\Documents\'
+# Generate a VMware vSphere As Built report in HTML & Word formats. Perform a health check to highlight particular issues which exist within the Vmware vSphere environment. Save the report to the 'H:\Documents\' folder.
+New-AsBuiltReport -Report 'VMware.vSphere' -Target '192.168.1.100' -Username 'admin' -Password 'admin' -Format HTML,Word -EnableHealthCheck -OutputFolderPath 'H:\Documents\'
 
-# The following creates a VMware vSphere As Built report in HTML & Word formats, while displaying Verbose messages to the console
-PS C:\>New-AsBuiltReport -Report VMware.vSphere -Target 192.168.1.100 -Username admin -Password admin -Format HTML,Word -OutputFolderPath 'H:\Documents\' -Verbose
+# Generate a Nutanix Prism Element As Built Report using specified username and password credentials. Specify the report configuration file to be used. Export report to Text, HTML & DOCX formats. Use the default report style. Save the report to the '/Users/Tim/Documents' folder. Display verbose messages to the console.
+New-AsBuiltReport -Report 'Nutanix.PrismElement' -Target 'prism.nutanix.local' -Username 'demo' -Password 'demo' -Format Text,Html,Word -OutputFolderPath '/Users/Tim/Documents' -ReportConfigFilePath '/Users/Tim/AsBuiltReport/AsBuiltReport.Nutanix.PrismElement.json' -Verbose
 
-# The following creates a Pure Storage FlashArray As Built report in Text format and appends a timestamp to the filename. It also uses stored credentials to connect to the system.
-PS C:\>$Creds = Get-Credential
-PS C:\>New-AsBuiltReport -Report PureStorage.FlashArray -Target 192.168.1.100 -Credential $Creds -Format Text -Timestamp -OutputFolderPath 'H:\Documents\'
+# Generate a Pure Storage FlashArray As Built Report in Text format and append a timestamp to the filename. Use stored credentials for authentication. Use the default Pure Storage report style. Save the reports to the 'H:\Documents' folder.
+$Credentials = Get-Credential
+New-AsBuiltReport -Report 'PureStorage.FlashArray' -Target '192.168.1.100' -Credential $Credentials -Format Text -Timestamp -OutputFolderPath 'H:\Documents\'
 
 # The following creates a Cisco UCS Manager As Built report in default format (Word) with a customised style.
-PS C:\>New-AsBuiltReport -Report Cisco.UCSManager -Target 192.168.1.100 -Username admin -Password admin -StyleFilePath 'C:\scripts\ACME.ps1' -OutputFolderPath 'H:\Documents\'
-
-# The following creates a VMware NSX-V As Built report in HTML format, using the configuration in the asbuilt.json file located in the C:\scripts\ folder.
-PS C:\>New-AsBuiltReport -Report VMware.NSXv -Target 192.168.1.100 -Username admin -Password admin -Format HTML -AsBuiltConfigFilePath 'C:\scripts\asbuilt.json' -OutputFolderPath 'H:\Documents\'
+New-AsBuiltReport -Report 'Cisco.UCSManager' -Target '192.168.1.100' -Username 'admin' -Password 'admin' -StyleFilePath 'C:\scripts\ACME.ps1' -OutputFolderPath 'H:\Documents\'
 
 # The following creates a Nutanix Prism Element As Built report in HTML format, with a custom filename.
-PS C:\>New-AsBuiltReport -Report VMware.NSXv -Target 192.168.1.100 -Username admin -Password admin -Format HTML -AsBuiltConfigFilePath 'C:\scripts\asbuilt.json' -OutputFolderPath 'H:\Documents\' -Filename 'My Nutanix Configuration'
+New-AsBuiltReport -Report 'Nutanix.PrismElement' -Target '192.168.1.100' -Username 'admin' -Password 'admin' -Format HTML -AsBuiltConfigFilePath 'C:\scripts\asbuilt.json' -OutputFolderPath 'H:\Documents\' -Filename 'My Nutanix Configuration'
 ```
 
-## :pencil: Notes
-- Table Of Contents (TOC) may be missing in Word formatted report
+## :x: Known Issues
+- **Table Of Contents (TOC) is missing in Word formatted report**
 
-    When opening the DOCX report, MS Word prompts the following
+    When opening a Microsoft Word (DOCX) report for the first time, you will be prompted with the following warning;
 
     `"This document contains fields that may refer to other files. Do you want to update the fields in this document?"`
 
     `Yes / No`
 
-    Clicking `No` will prevent the TOC fields being updated and leaving the TOC empty.
+    Clicking No will prevent the TOC fields from being updated, leaving the Table of Contents empty.
+
+    Always reply Yes to this message when prompted by Microsoft Word to ensure the Table of Contents is updated.
+
+    Save the document to prevent future prompts when opening the document.
+
+- **Images are missing from reports generated using Linux or macOS**
 
-    Always reply `Yes` to this message when prompted by MS Word.
+    Unfortunately due to [breaking changes](https://learn.microsoft.com/en-gb/dotnet/core/compatibility/core-libraries/6.0/system-drawing-common-windows-only) in .NET 6, images are no longer supported for reports generated using Linux or macOS.