initial Commit
This commit is contained in:
Torsten Brendgen
396
Readme.md
Normal file
396
Readme.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# Resolve-DSCConfigurationData
|
||||
|
||||
`Resolve-DSCConfigurationData` resolves parameter, variable, and expression references in DSC configuration data.
|
||||
|
||||
Typical flow:
|
||||
|
||||
```powershell
|
||||
$merged = Merge-DSCConfigurationData -Template $service -Deployment $environment
|
||||
$resolved = Resolve-DSCConfigurationData -ConfigurationData $merged
|
||||
```
|
||||
|
||||
Expressions use an ARM-like syntax:
|
||||
|
||||
```powershell
|
||||
"[parameters('DatabasePrefix')]"
|
||||
"[variables('ServiceDbPrefix')]"
|
||||
"[concat(parameters('DatabasePrefix'), '_', parameters('ServiceDatabaseSegment'))]"
|
||||
```
|
||||
|
||||
## Parameter Example
|
||||
|
||||
This block shows all currently supported parameter properties.
|
||||
|
||||
```powershell
|
||||
@{
|
||||
Parameters = @{
|
||||
DatabasePrefix = @{
|
||||
Type = 'string'
|
||||
|
||||
# Optional explicit value. If Value is present, it wins over DefaultValue.
|
||||
Value = 'SharePoint'
|
||||
|
||||
# Used when Value is not present.
|
||||
DefaultValue = 'SharePoint'
|
||||
|
||||
# If true, Value or DefaultValue must be present and not empty.
|
||||
Required = $true
|
||||
|
||||
# Optional fixed set of valid values.
|
||||
AllowedValues = @(
|
||||
'SharePoint',
|
||||
'ProjectServer',
|
||||
'Search'
|
||||
)
|
||||
|
||||
# Optional string length validation.
|
||||
MinLength = 2
|
||||
MaxLength = 32
|
||||
|
||||
# Optional regex validation.
|
||||
Pattern = '^[A-Za-z][A-Za-z0-9_-]*$'
|
||||
|
||||
# Metadata for later reporting/output tooling. The resolver does not mask values yet.
|
||||
Sensitive = $false
|
||||
|
||||
# Emits a warning when the parameter is present.
|
||||
Deprecated = @{
|
||||
Message = @{
|
||||
'de-DE' = 'Der Parameter [DatabasePrefix] ist veraltet. Verwende [SharePointDatabasePrefix].'
|
||||
'en-US' = 'Parameter [DatabasePrefix] is deprecated. Use [SharePointDatabasePrefix].'
|
||||
}
|
||||
}
|
||||
|
||||
Metadata = @{
|
||||
Description = @{
|
||||
'de-DE' = 'Praefix fuer alle von der SharePoint-Farm angelegten Datenbanken.'
|
||||
'en-US' = 'Prefix for all databases created by the SharePoint farm.'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `Value` wins over `DefaultValue`.
|
||||
- `Required`, `AllowedValues`, `MinLength`, `MaxLength`, and `Pattern` are validated by the resolver.
|
||||
- `Sensitive` is currently metadata only.
|
||||
- `Deprecated.Message` can be a string or a localized hashtable.
|
||||
- Optional string parameters can allow empty values with a pattern like `'^$|^[A-Za-z][A-Za-z0-9_-]*$'`.
|
||||
|
||||
## Variable Example
|
||||
|
||||
Variables may reference parameters and other variables. Nested variable references are supported. Circular references are rejected.
|
||||
|
||||
```powershell
|
||||
@{
|
||||
Parameters = @{
|
||||
DatabasePrefix = @{
|
||||
Type = 'string'
|
||||
DefaultValue = 'SharePoint'
|
||||
}
|
||||
DomainLabel = @{
|
||||
Type = 'string'
|
||||
Value = 'LAN'
|
||||
}
|
||||
Landscape = @{
|
||||
Type = 'string'
|
||||
Value = 'Test'
|
||||
AllowedValues = @(
|
||||
'Prod',
|
||||
'Test'
|
||||
)
|
||||
}
|
||||
ServiceDatabaseSegment = @{
|
||||
Type = 'string'
|
||||
DefaultValue = 'Services'
|
||||
}
|
||||
}
|
||||
|
||||
Variables = @{
|
||||
StageCode = "[if(equals(parameters('Landscape'), 'Test'), 'TST', 'PRD')]"
|
||||
DatabasePrefix = "[joinNotEmpty('_', parameters('DatabasePrefix'), parameters('DomainLabel'), variables('StageCode'))]"
|
||||
ServiceDbPrefix = "[joinNotEmpty('_', variables('DatabasePrefix'), parameters('ServiceDatabaseSegment'))]"
|
||||
ConfigDbName = "[joinNotEmpty('_', variables('DatabasePrefix'), 'Farm_Config')]"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```text
|
||||
StageCode : TST
|
||||
DatabasePrefix : SharePoint_LAN_TST
|
||||
ServiceDbPrefix : SharePoint_LAN_TST_Services
|
||||
ConfigDbName : SharePoint_LAN_TST_Farm_Config
|
||||
```
|
||||
|
||||
## Functions
|
||||
|
||||
### References
|
||||
|
||||
```powershell
|
||||
"[parameters('DatabasePrefix')]"
|
||||
"[variables('ServiceDbPrefix')]"
|
||||
```
|
||||
|
||||
`parameters(name)` returns the effective parameter value. `Value` is used before `DefaultValue`.
|
||||
|
||||
`variables(name)` resolves another variable. Variables may reference other variables.
|
||||
|
||||
### String Composition
|
||||
|
||||
```powershell
|
||||
"[concat('SharePoint', '_', 'Services')]"
|
||||
# SharePoint_Services
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[format('{0}_{1}_{2}', parameters('DatabasePrefix'), parameters('DomainLabel'), parameters('Landscape'))]"
|
||||
# SharePoint_LAN_Test
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[joinNotEmpty('_', parameters('DatabasePrefix'), parameters('DomainLabel'), '', 'Services')]"
|
||||
# SharePoint_LAN_Services
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[defaultIfEmpty(parameters('DatabasePrefix'), 'SharePoint')]"
|
||||
# SharePoint, when DatabasePrefix is empty
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[coalesce(parameters('CustomPrefix'), parameters('DatabasePrefix'), 'SharePoint')]"
|
||||
# First non-empty value
|
||||
```
|
||||
|
||||
### Conditions And Boolean Logic
|
||||
|
||||
```powershell
|
||||
"[if(equals(parameters('Landscape'), 'Test'), 'TST', 'PRD')]"
|
||||
# TST
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[equals(parameters('Landscape'), 'Test')]"
|
||||
"[notEquals(parameters('Landscape'), 'Prod')]"
|
||||
"[and(equals(parameters('Landscape'), 'Test'), not(empty(parameters('DatabasePrefix'))))]"
|
||||
"[or(equals(parameters('Landscape'), 'Prod'), equals(parameters('Landscape'), 'Test'))]"
|
||||
"[not(empty(parameters('DatabasePrefix')))]"
|
||||
```
|
||||
|
||||
### Case And Text
|
||||
|
||||
```powershell
|
||||
"[toLower('BGW-LAN')]"
|
||||
# bgw-lan
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[toUpper('bgw-lan')]"
|
||||
# BGW-LAN
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[trim(' SharePoint ')]"
|
||||
"[trimStart(' SharePoint')]"
|
||||
"[trimEnd('SharePoint ')]"
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[replace('BGW-LAN', '-', '_')]"
|
||||
# BGW_LAN
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[substring('SharePoint', 5, 5)]"
|
||||
# Point
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[indexOf('BGW', 1)]"
|
||||
# G
|
||||
```
|
||||
|
||||
`firstIndexOf` and `lastIndexOf` return the first or last function argument:
|
||||
|
||||
```powershell
|
||||
"[firstIndexOf('a', 'b', 'c')]"
|
||||
# a
|
||||
|
||||
"[lastIndexOf('a', 'b', 'c')]"
|
||||
# c
|
||||
```
|
||||
|
||||
### Name Cleanup
|
||||
|
||||
```powershell
|
||||
"[sanitizeName(' SharePoint LAN/Test DB ')]"
|
||||
# SharePoint_LAN_Test_DB
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[sanitizeName(' SharePoint LAN/Test DB ', '-')]"
|
||||
# SharePoint-LAN-Test-DB
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[normalizeSeparator('__SharePoint___LAN_Test__', '_')]"
|
||||
# SharePoint_LAN_Test
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[prefixIfNotEmpty('LAN', 'BGW-')]"
|
||||
# BGW-LAN
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[suffixIfNotEmpty('SharePoint', '_DB')]"
|
||||
# SharePoint_DB
|
||||
```
|
||||
|
||||
### Collections
|
||||
|
||||
```powershell
|
||||
"[split(parameters('DomainFQDN'), '.')]"
|
||||
# @('bgw-online', 'de')
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[join(split(parameters('DomainFQDN'), '.'), '_')]"
|
||||
# bgw-online_de
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[first(split(parameters('DomainFQDN'), '.'))]"
|
||||
# bgw-online
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[last(split(parameters('DomainFQDN'), '.'))]"
|
||||
# de
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[take(split(parameters('DomainFQDN'), '.'), 1)]"
|
||||
# @('bgw-online')
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[skip(split(parameters('DomainFQDN'), '.'), 1)]"
|
||||
# @('de')
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[unique(split('SP.SP.SQL', '.'))]"
|
||||
# @('SP', 'SQL')
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[sort(split('SQL.SP.APP', '.'))]"
|
||||
# @('APP', 'SP', 'SQL')
|
||||
```
|
||||
|
||||
### Inspection
|
||||
|
||||
```powershell
|
||||
"[contains(parameters('DomainFQDN'), 'online')]"
|
||||
# True
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[contains(split(parameters('DomainFQDN'), '.'), 'de')]"
|
||||
# True
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[startsWith(parameters('DomainFQDN'), 'bgw')]"
|
||||
# True
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[endsWith(parameters('DomainFQDN'), 'de')]"
|
||||
# True
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[length(split(parameters('DomainFQDN'), '.'))]"
|
||||
# 2
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[empty(parameters('OptionalValue'))]"
|
||||
# True, when OptionalValue is empty
|
||||
```
|
||||
|
||||
### Padding
|
||||
|
||||
```powershell
|
||||
"[padLeft('1', 2, '0')]"
|
||||
# 01
|
||||
```
|
||||
|
||||
```powershell
|
||||
"[padRight('SP', 4, '0')]"
|
||||
# SP00
|
||||
```
|
||||
|
||||
## Full Function List
|
||||
|
||||
- `parameters(name)`
|
||||
- `variables(name)`
|
||||
- `concat(value1, value2, ...)`
|
||||
- `format(formatString, value1, value2, ...)`
|
||||
- `coalesce(value1, value2, ...)`
|
||||
- `defaultIfEmpty(value, defaultValue)`
|
||||
- `if(condition, trueValue, falseValue)`
|
||||
- `equals(left, right)`
|
||||
- `notEquals(left, right)`
|
||||
- `and(value1, value2, ...)`
|
||||
- `or(value1, value2, ...)`
|
||||
- `not(value)`
|
||||
- `toLower(value)`
|
||||
- `toUpper(value)`
|
||||
- `firstIndexOf(value1, value2, ...)`
|
||||
- `lastIndexOf(value1, value2, ...)`
|
||||
- `indexOf(value, index)`
|
||||
- `substring(value, startIndex)`
|
||||
- `substring(value, startIndex, length)`
|
||||
- `replace(value, oldValue, newValue)`
|
||||
- `sanitizeName(value)`
|
||||
- `sanitizeName(value, separator)`
|
||||
- `normalizeSeparator(value, separator)`
|
||||
- `prefixIfNotEmpty(value, prefix)`
|
||||
- `suffixIfNotEmpty(value, suffix)`
|
||||
- `contains(value, search)`
|
||||
- `startsWith(value, search)`
|
||||
- `endsWith(value, search)`
|
||||
- `split(value, separator)`
|
||||
- `join(array, separator)`
|
||||
- `joinNotEmpty(separator, value1, value2, ...)`
|
||||
- `take(array, count)`
|
||||
- `skip(array, count)`
|
||||
- `first(array)`
|
||||
- `last(array)`
|
||||
- `unique(array)`
|
||||
- `sort(array)`
|
||||
- `trim(value)`
|
||||
- `trimStart(value)`
|
||||
- `trimEnd(value)`
|
||||
- `padLeft(value, totalWidth)`
|
||||
- `padLeft(value, totalWidth, paddingCharacter)`
|
||||
- `padRight(value, totalWidth)`
|
||||
- `padRight(value, totalWidth, paddingCharacter)`
|
||||
- `length(value)`
|
||||
- `empty(value)`
|
||||
|
||||
## Validation
|
||||
|
||||
Run the tests:
|
||||
|
||||
```powershell
|
||||
Invoke-Pester -Script '.\PowerShell\Resolve-DSCConfigurationData\.tests\Resolve-DSCConfigurationData.Tests.ps1'
|
||||
```
|
||||
Reference in New Issue
Block a user