Blog/content/posts/psmodulebase/index.md

123 lines
3.3 KiB
Markdown
Raw Normal View History

2022-03-22 08:34:32 +01:00
---
2022-04-26 09:35:14 +02:00
title: 'How to get your PowerShell Module Base root path'
2022-03-22 08:34:32 +01:00
date: 2022-03-21T09:14:41+01:00
2022-04-26 09:35:14 +02:00
#draft: true
2022-03-22 08:34:32 +01:00
categories: ['PowerShell']
tags: ['ModuleBase', 'config']
# lastmod: 2022-03-21T09:14:41+01:00
# showDateUpdated: true
# custom overrides for pages
# showDate: false
# showAuthor: false
# showWordCount: false
# showReadingTime: false
# showTableOfContents: false
# showTaxonomies: false
# showEdit: false
# sharingLinks: [null]
---
![note](note.jpg 'Photo by [Sigmund](https://unsplash.com/@sigmund) on [Unsplash](https://unsplash.com)')
## 🖼️ Intro
2022-04-26 09:35:14 +02:00
This article explains with a practical example how to determine and use the current module base path.
Sometimes you want to use a basic config file for your module. This config file could be used to define basic
settings for your module. These module wide default settings should placed and shipped within your module.
2022-03-22 08:34:32 +01:00
Therefore you can use the automatic variable `$MyInvocation`, especially with its properties
`$MyInvocation.MyCommand.Module.ModuleBase`. This returns the full path to your current module base folder, which
2022-04-26 09:35:14 +02:00
can be used by your function to join a path for your config file.
2022-03-22 08:34:32 +01:00
## 📑 `.\config.psd1` config file
Let's assume you start a new module and you need multiple config keys to work with. So you usually create a
2022-04-26 09:35:14 +02:00
**JSON** or **P**ower**S**hell **D**ata format based config file:
2022-03-22 08:34:32 +01:00
```powershell
{
# Logging
OutputLevel = 'Detailed'
DefaultTarget = 'Console'
LogRetentionInWeeks = 4
# DataSource
CouchDBURI = 'http://localhost'
MongoDBURI = 'http://mongodb'
# ...
# ...
}
```
## 🔎 `Get-ConfigValue` helper function
2022-04-26 09:35:14 +02:00
Now you can use `$MyInvocation.MyCommand.Module.ModuleBase` with a helper function, to parse the path to your config
file, and return the stored default values:
2022-03-22 08:34:32 +01:00
```powershell
function Get-ConfigValue {
<#
.SYNOPSIS
Returns the value of a given config file key.
2022-04-26 09:35:14 +02:00
.PARAMETER FromKey
2022-03-22 08:34:32 +01:00
Config file key.
.OUTPUTS
[string]
.EXAMPLE
2022-04-26 09:35:14 +02:00
Get-ConfigValue -FromKey 'OutputLevel'
2022-03-22 08:34:32 +01:00
.NOTES
Private module helper function. Used by other function within your module.
#>
[CmdletBinding()]
[OutputType([string])]
param (
[Parameter(Mandatory = $true, HelpMessage = 'Existing key from config file.')]
2022-04-26 09:35:14 +02:00
[string]$FromKey
2022-03-22 08:34:32 +01:00
)
begin { }
process {
2022-04-26 09:35:14 +02:00
$ErrorActionPreference = 'Stop'
2022-03-22 08:34:32 +01:00
$ModuleBase = $MyInvocation.MyCommand.Module.ModuleBase
$ConfigFile = Join-Path -Path $ModuleBase -ChildPath 'config.psd1'
if (Test-Path -Path $ConfigFile) {
try {
$Config = Import-PowerShellDataFile -Path $ConfigFile
2022-04-26 09:35:14 +02:00
Write-Output $Config.$FromKey
2022-03-22 08:34:32 +01:00
}
catch {
2022-04-26 09:35:14 +02:00
Write-Error -Message $_.Exception.Message
2022-03-22 08:34:32 +01:00
}
}
else {
2022-04-26 09:35:14 +02:00
Write-Error -Message 'Config file not found!'
2022-03-22 08:34:32 +01:00
}
}
end { }
}
```
## 💭 Final Thoughts
2022-04-26 09:35:14 +02:00
All you need to to is using the `Get-ConfigValue -FromKey '<example key>'` in your functions to get any value
defined in your config file.
2022-03-22 08:34:32 +01:00
As far as I know, that's the simplest way to get your module root and using it with a config file.
{{< alert >}}
2022-04-26 09:35:14 +02:00
Do not to store any sensitive data in you config file. User specific data should also be stored in a user
context and not in a global module wide config file.
2022-03-22 08:34:32 +01:00
{{< /alert >}}