Merge pull request #1 from d365collaborative/ready-for-release

Ready for release

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/workflows/build.yml

@@ -0,0 +1,24 @@
+on:
+  push:
+    branches:
+      - master
+      - main
+
+jobs:
+  build:
+
+    runs-on: windows-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install Prerequisites
+      run: .\build\vsts-prerequisites.ps1
+      shell: powershell
+    - name: Validate
+      run: .\build\vsts-validate.ps1
+      shell: powershell
+    - name: Build
+      run: .\build\vsts-build.ps1 -ApiKey $env:APIKEY
+      shell: powershell
+      env:
+        APIKEY: ${{ secrets.ApiKey }}

.github/workflows/validate.yml

@@ -0,0 +1,15 @@
+on: [pull_request]
+
+jobs:
+  validate:
+
+    runs-on: windows-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install Prerequisites
+      run: .\build\vsts-prerequisites.ps1
+      shell: powershell
+    - name: Validate
+      run: .\build\vsts-validate.ps1
+      shell: powershell

.gitignore

@@ -0,0 +1,22 @@
+
+# ignore the settings folder and files for VSCode and PSS
+.vscode/*
+*.psproj
+*TempPoint*
+
+# Ignore staging info from Visual Studio
+library/d365bap.tools/.vs/*
+library/d365bap.tools/d365bap.tools/bin/*
+library/d365bap.tools/d365bap.tools/obj/*
+
+# ignore PowerShell Studio MetaData
+d365bap.tools/d365bap.tools.psproj
+d365bap.tools/d365bap.tools.psproj.bak
+d365bap.tools/d365bap.tools.psprojs
+d365bap.tools/d365bap.tools.psproj
+
+# ignore the TestResults
+TestResults/*
+
+# ignore the publishing Directory
+publish/*

LICENSE

@@ -1,6 +1,6 @@
-MIT License
+MIT License
 
-Copyright (c) 2024 d365collaborative
+Copyright (c) 2024 MötzJensen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -1,2 +1,111 @@
-# d365bap.tools
-Tools used for Business Application Platform, One Dynamics One Platform - D365FO + Dataverse
+# **d365bap.tools**
+
+A PowerShell module to handle different management tasks related to Business Application Platform, which consist of Microsoft Dynamics 365 Finance & Operations (D365FO) and Dataverse (PowerPlatform)
+
+Read more about D365FO on [learn.microsoft.com](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/fin-ops/).
+
+Read more about Dataverse on [learn.microsoft.com](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/).
+
+Available on PowerShell Gallery:
+[d365bap.tools](https://www.powershellgallery.com/packages/d365bap.tools).
+
+## Table of contents
+* [Getting started](#getting-started)
+* [Getting help](#getting-help)
+* [Contributing](#contributing)
+* [Dependencies](#dependencies)
+
+## Getting started
+### Install the latest module
+```PowerShell
+Install-Module -Name d365bap.tools
+```
+
+### Install without administrator privileges
+```PowerShell
+Install-Module -Name d365bap.tools -Scope CurrentUser
+```
+### List all available commands / functions
+
+```PowerShell
+Get-Command -Module d365bap.tools
+```
+
+### Update the module
+
+```PowerShell
+Update-Module -name d365bap.tools
+```
+
+### Update the module - force
+
+```PowerShell
+Update-Module -name d365bap.tools -Force
+```
+
+## Preparing the first execution
+The module is leveraging the Az.Account module, to obtain all the needed OAuth 2.0 tokens, for the different REST API's spread across the BAP (Business Application Platform) / ODOP (One Dynamics One Platform).
+
+So you will need to sign in with an user account with enough permissions / privileges for the different endpoints. This **must be done prior** running any command from the d365bap.tools module.
+
+```
+Login-AzAccount -TenantId abd...
+```
+
+Depending on which PowerShell console (v5 / v7+) - you will have different sign-in experiences. There are different ways to utilized the Web Browser experience (Device Authentication), which allows for saved credentials to be utilized while authenticating.
+
+```
+Login-AzAccount -UseDeviceAuthentication -TenantId abd...
+```
+
+## Getting help
+
+[The wiki](https://github.com/d365collaborative/d365bap.tools/wiki) contains more details about installation and also guides to help you with some common tasks. It also contains documentation for all the module's commands. Expand the wiki's `Pages` control at the top of the content sidebar to view and search the list of command documentation pages.
+
+Another way to learn about the different cmdlets available is to install the tools onto your machine.
+You can also visit the **'docs'** folder in this repository (look at the top). Click this link [**docs**](https://github.com/d365collaborative/d365bap.tools/tree/master/docs) to jump straight inside.
+
+Since the project started we have adopted and extended the comment based help inside each cmdlet / function. This means that every single command contains at least one fully working example on how to run it and what to expect from the cmdlet.
+
+**Getting help inside the PowerShell console**
+
+Getting help is as easy as writing **Get-Help CommandName**
+
+```PowerShell
+Get-Help Get-BapEnvironment
+```
+
+*This will display the available default help.*
+
+Getting the entire help is as easy as writing **Get-Help CommandName -Full**
+
+```PowerShell
+Get-Help Get-BapEnvironment -Full
+```
+
+*This will display all available help content there is for the cmdlet / function*
+
+Getting all the available examples for a given command is as easy as writing **Get-Help CommandName -Examples**
+
+```PowerShell
+Get-Help Get-BapEnvironment -Examples
+```
+
+*This will display all the available **examples** for the cmdlet / function.*
+
+We know that when you are learning about new stuff and just want to share your findings with your peers, working with help inside a PowerShell session isn't that great.
+
+### Web based help and examples
+We have implemented **platyPS** (https://github.com/PowerShell/platyPS) to generate markdown files for each cmdlet / function available in the module. These files are hosted here on github for you to consume in your web browser and the give you the look and feel of other documentation sites.
+
+The generated help markdown files are located inside the **'docs'** folder in this repository. Click this [link](https://github.com/d365collaborative/d365bap.tools/tree/master/docs) to jump straight inside.
+
+They are also available in the [wiki](https://github.com/d365collaborative/d365bap.tools/wiki) in the list of pages.
+
+## Contributing
+
+Want to contribute to the project? We'd love to have you! Visit our [contributing.md](https://github.com/d365collaborative/d365bap.tools/blob/master/contributing.md) for a jump start.
+
+## Dependencies
+
+This module depends on other modules. The dependencies are documented in the [dependency graph](https://github.com/d365collaborative/d365bap.tools/network/dependencies) and the Dependencies section of the Package Details of the [package listing](https://www.powershellgallery.com/packages/d365bap.tools) in the PowerShell Gallery.

azure-pipelines.yml

@@ -0,0 +1,20 @@
+pool:
+  vmImage: "windows-latest"
+steps:
+- task: PowerShell@2
+  displayName: Prerequisites
+  inputs:
+    targetType: filePath
+    filePath: './build/vsts-prerequisites.ps1'
+
+- task: PowerShell@2
+  displayName: Validate
+  inputs:
+    targetType: filePath
+    filePath: './build/vsts-validate.ps1'
+
+- task: PublishTestResults@2
+  displayName: 'Publish Test Results **/TEST-*.xml'
+  inputs:
+    testResultsFormat: NUnit
+  condition: always()

build/vsts-build.ps1

@@ -0,0 +1,131 @@
+<#
+This script publishes the module to the gallery.
+It expects as input an ApiKey authorized to publish the module.
+
+Insert any build steps you may need to take before publishing it here.
+#>
+param (
+	$ApiKey,
+
+	$WorkingDirectory,
+
+	$Repository = 'PSGallery',
+
+	[switch]
+	$LocalRepo,
+
+	[switch]
+	$SkipPublish,
+
+	[switch]
+	$AutoVersion,
+
+	[switch]
+	$Build
+)
+
+#region Handle Working Directory Defaults
+if (-not $WorkingDirectory)
+{
+	if ($env:RELEASE_PRIMARYARTIFACTSOURCEALIAS)
+	{
+		$WorkingDirectory = Join-Path -Path $env:SYSTEM_DEFAULTWORKINGDIRECTORY -ChildPath $env:RELEASE_PRIMARYARTIFACTSOURCEALIAS
+	}
+	else { $WorkingDirectory = $env:SYSTEM_DEFAULTWORKINGDIRECTORY }
+}
+if (-not $WorkingDirectory) { $WorkingDirectory = Split-Path $PSScriptRoot }
+#endregion Handle Working Directory Defaults
+
+# Build Library
+if ($Build) {
+	dotnet build "$WorkingDirectory\library\d365bap.tools.sln"
+	if ($LASTEXITCODE -ne 0) {
+		throw "Failed to build d365bap.tools.dll!"
+	}
+}
+
+# Prepare publish folder
+Write-PSFMessage -Level Important -Message "Creating and populating publishing directory"
+$publishDir = New-Item -Path $WorkingDirectory -Name publish -ItemType Directory -Force
+Copy-Item -Path "$($WorkingDirectory)\d365bap.tools" -Destination $publishDir.FullName -Recurse -Force
+
+#region Gather text data to compile
+$text = @()
+$processed = @()
+
+# Gather Stuff to run before
+foreach ($filePath in (& "$($PSScriptRoot)\..\d365bap.tools\internal\scripts\preimport.ps1"))
+{
+	if ([string]::IsNullOrWhiteSpace($filePath)) { continue }
+
+	$item = Get-Item $filePath
+	if ($item.PSIsContainer) { continue }
+	if ($item.FullName -in $processed) { continue }
+	$text += [System.IO.File]::ReadAllText($item.FullName)
+	$processed += $item.FullName
+}
+
+# Gather commands
+Get-ChildItem -Path "$($publishDir.FullName)\d365bap.tools\internal\functions\" -Recurse -File -Filter "*.ps1" | ForEach-Object {
+	$text += [System.IO.File]::ReadAllText($_.FullName)
+}
+Get-ChildItem -Path "$($publishDir.FullName)\d365bap.tools\functions\" -Recurse -File -Filter "*.ps1" | ForEach-Object {
+	$text += [System.IO.File]::ReadAllText($_.FullName)
+}
+
+# Gather stuff to run afterwards
+foreach ($filePath in (& "$($PSScriptRoot)\..\d365bap.tools\internal\scripts\postimport.ps1"))
+{
+	if ([string]::IsNullOrWhiteSpace($filePath)) { continue }
+
+	$item = Get-Item $filePath
+	if ($item.PSIsContainer) { continue }
+	if ($item.FullName -in $processed) { continue }
+	$text += [System.IO.File]::ReadAllText($item.FullName)
+	$processed += $item.FullName
+}
+#endregion Gather text data to compile
+
+#region Update the psm1 file
+$fileData = Get-Content -Path "$($publishDir.FullName)\d365bap.tools\d365bap.tools.psm1" -Raw
+$fileData = $fileData.Replace('"<was not compiled>"', '"<was compiled>"')
+$fileData = $fileData.Replace('"<compile code into here>"', ($text -join "`n`n"))
+[System.IO.File]::WriteAllText("$($publishDir.FullName)\d365bap.tools\d365bap.tools.psm1", $fileData, [System.Text.Encoding]::UTF8)
+#endregion Update the psm1 file
+
+#region Updating the Module Version
+if ($AutoVersion)
+{
+	Write-PSFMessage -Level Important -Message "Updating module version numbers."
+	try { [version]$remoteVersion = (Find-Module 'd365bap.tools' -Repository $Repository -ErrorAction Stop).Version }
+	catch
+	{
+		Stop-PSFFunction -Message "Failed to access $($Repository)" -EnableException $true -ErrorRecord $_
+	}
+	if (-not $remoteVersion)
+	{
+		Stop-PSFFunction -Message "Couldn't find d365bap.tools on repository $($Repository)" -EnableException $true
+	}
+	$newBuildNumber = $remoteVersion.Build + 1
+	[version]$localVersion = (Import-PowerShellDataFile -Path "$($publishDir.FullName)\d365bap.tools\d365bap.tools.psd1").ModuleVersion
+	Update-ModuleManifest -Path "$($publishDir.FullName)\d365bap.tools\d365bap.tools.psd1" -ModuleVersion "$($localVersion.Major).$($localVersion.Minor).$($newBuildNumber)"
+}
+#endregion Updating the Module Version
+
+#region Publish
+if ($SkipPublish) { return }
+if ($LocalRepo)
+{
+	# Dependencies must go first
+	Write-PSFMessage -Level Important -Message "Creating Nuget Package for module: PSFramework"
+	New-PSMDModuleNugetPackage -ModulePath (Get-Module -Name PSFramework).ModuleBase -PackagePath .
+	Write-PSFMessage -Level Important -Message "Creating Nuget Package for module: d365bap.tools"
+	New-PSMDModuleNugetPackage -ModulePath "$($publishDir.FullName)\d365bap.tools" -PackagePath .
+}
+else
+{
+	# Publish to Gallery
+	Write-PSFMessage -Level Important -Message "Publishing the d365bap.tools module to $($Repository)"
+	Publish-Module -Path "$($publishDir.FullName)\d365bap.tools" -NuGetApiKey $ApiKey -Force -Repository $Repository
+}
+#endregion Publish

build/vsts-prerequisites.ps1

@@ -0,0 +1,25 @@
+param (
+    [string]
+    $Repository = 'PSGallery'
+)
+
+$modules = @("Pester", "PSFramework", "PSModuleDevelopment", "PSScriptAnalyzer")
+
+# Automatically add missing dependencies
+$data = Import-PowerShellDataFile -Path "$PSScriptRoot\..\d365bap.tools\d365bap.tools.psd1"
+foreach ($dependency in $data.RequiredModules) {
+    if ($dependency -is [string]) {
+        if ($modules -contains $dependency) { continue }
+        $modules += $dependency
+    }
+    else {
+        if ($modules -contains $dependency.ModuleName) { continue }
+        $modules += $dependency.ModuleName
+    }
+}
+
+foreach ($module in $modules) {
+    Write-Host "Installing $module" -ForegroundColor Cyan
+    Install-Module $module -Force -SkipPublisherCheck -Repository $Repository
+    Import-Module $module -Force -PassThru
+}