You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As a user and integrating vendor, I want to be able to quickly map the exit code from the PowerShell and Windows PowerShell adapters to their semantics, so I can understand what went wrong at a high-level before I investigate the error specifically.
Currently, the Microsoft.DSC/PowerShell and Microsoft.Windows/WindowsPowerShell adapters only define exit codes 0 (success) and 1 (error).
Define reusable semantic exit codes for the adapter in psDscAdapter.psm1 and use them in the adapter code.
For example,
enum DscAdapterExitCode {
Success =0
Failure
InvocationError
ImportPsdscModuleError
ScriptBasedResourcesWindowsOnly
BinaryResourceWindowsPowerShellOnly
BinaryResourceUnsupported
ImplementationDetailUnsupported
ResourceNotFound
InputJsonErrorCreatingConfigurationObject
InputJsonErrorListingDscResourceTypes
DscResourceModuleNotFound
IncompleteGetResult
}
<# public function Write-JsonMessage.SYNOPSIS This function writes a JSON formatted trace message to the host stderr..DESCRIPTION This function is designed to write a JSON formatted trace message to the host stderr. The trace message is intended to be used for debugging purposes and can be parsed by other tools, like DSC itself..PARAMETERMessage The message to be written to the host stderr. This message will be written as a JSON object with the key being the value of the Level parameter..PARAMETERLevel The level of the trace message. The default value is 'Debug'. The valid values are 'Trace', 'Debug', 'Info', 'Warning', and 'Error'. These levels map to the levels that DSC uses for trace messages.#>functionWrite-JsonMessage {
[CmdletBinding(HelpUri='')]
param(
[Parameter(Mandatory=$true,Position=0)]
[string]$Message,
[Parameter(Position=1)]
[ValidateSet('Trace','Debug','Info','Warning','Error')]
[string]$Level='Debug'
)
$json=@{ $Level=$Message } |ConvertTo-Json-Compress
$host.ui.WriteErrorLine($json)
}
classDscAdapterError {
[int] $ExitCode
[string] $ErrorMessage
WriteAndExit() {
Write-JsonMessage-Level Error -Message $this.ErrorMessageexit$this.ExitCode
}
static [DscAdapterError] ImportPsdscModuleError([string]$importModuleError) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::ImportPsdscModuleError
ErrorMessage="Could not import PSDesiredStateConfiguration 1.1 in Windows PowerShell. $importModuleError"
}
}
static [DscAdapterError] ScriptBasedResourcesWindowsOnly([DscResourceInfo]$resource) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::ScriptBasedResourcesWindowsOnly
ErrorMessage="Resource $resource is script-based. Script-based resources are only supported on Windows."
}
}
static [DscAdapterError] InvocationError([string]$operation, [DscResourceInfo]$resource, [string]$errorMessage) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::InvocationError
ErrorMessage="Error invoking '$operation' on ${resource}: $errorMessage"
}
}
static [DscAdapterError] BinaryResourceWindowsPowerShellOnly([DscResourceInfo]$resource) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::BinaryResourceWindowsPowerShellOnly
ErrorMessage="Resource $resource is a binary resource. Only the File, Log, and SignatureValidation binary resources are supported. To use a supported binary resource, use the Microsoft.DSC/WindowsPowerShell adapter."
}
}
static [DscAdapterError] BinaryResourceUnsupported([DscResourceInfo]$resource) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::BinaryResourceUnsupported
ErrorMessage="Resource $resource is not a supported binary resource. Only the File, Log, and SignatureValidation binary resources are supported."
}
}
static [DscAdapterError] ImplementationDetailUnsupported([DscResourceInfo]$resource) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::ImplementationDetailUnsupported
ErrorMessage="Resource $resource has an unsupported implementation '$($resource.ImplementationDetail)'. Supported implementations are: $([dscResourceType].GetEnumNames())"
}
}
static [DscAdapterError] ResourceNotFound([string]$type, [string]$json) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::ResourceNotFound
ErrorMessage="Can not find type '$type' for resource '$json'. Please ensure that Get-DscResource returns this resource type."
}
}
static [DscAdapterError] InputJsonErrorCreatingConfigurationObject([string]$jsonInput) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::InputJsonError
ErrorMessage="Failed to create configuration object from provided input JSON: $jsonInput"
}
}
static [DscAdapterError] InputJsonErrorListingDscResourceTypes() {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::InputJsonError
ErrorMessage="Could not get list of DSC resource types from provided JSON."
}
}
static [DscAdapterError] DscResourceModuleNotFound() {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::DscResourceModuleNotFound
ErrorMessage="DSC resource module not found."
}
}
static [DscAdapterError] IncompleteGetResult([string]$resourceType) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::IncompleteGetResult
ErrorMessage="Incomplete GET for resource $resourceType"
}
}
static [DscAdapterError] UnknownError([string]$errorMessage) {
return [DscAdapterError]@{
ExitCode= [DscAdapterExitCode]::Failure
ErrorMessage=$errorMessage
}
}
}
Then, when you need to use a specific exit code:
# in psDscAdapter.psm1# For Linux/MacOS, only class based resources are supported and are called directly.if ($IsLinux) {
[DscAdapterError]::ScriptBasedResourcesWindowsOnly($cachedDscResourceInfo).WriteAndExit()
}
# in powershell.resource.ps1# load private functions of psDscAdapter stub module$psDscAdapter=Import-Module"$PSScriptRoot/psDscAdapter.psd1"-Force -PassThru
# get handle to adapter errors for semantic exit codes/messages$psDscAdapterError=$psDscAdapter.Invoke({ [DscAdapterError] })
# ...$psDscAdapterError::IncompleteGetForResource($ds.Name).WriteAndExit()
Then we could map the exit codes to their semantic meanings and reuse errors as needed. This proposal also includes the helper function Write-JsonMessage for sending a JSON Line back to DSC for debug, warnings, errors, etc.
While out of scope for now, we should also consider whether and how to do i18n for exit codes and error messages. In this proposal I'm just matching the use of en-US already in place for the module and adapter.
The text was updated successfully, but these errors were encountered:
@michaeltlombardi this sounds useful! Would the enum be able to specific non-sequential specific error codes? Would it be able to provide them as a negative integer or hexadecimal? ( I think "yes, yes, and yes", because it's just an [enum] )
@StartAutomating - Yup, DSC Resources can return any valid int32 as an exit code. In this case, I'm specifically talking about the PowerShell adapter resource, which hasn't defined semantic exit codes in the resource manifest with the exitCodes property - the resource manifest only defines success and failure:
Although as we discovered in #407 (addressed in #410), you have to specify the exit codes in the manifest as integers, you can't specify them as hexadecimals.
Summary of the new feature / enhancement
As a user and integrating vendor, I want to be able to quickly map the exit code from the PowerShell and Windows PowerShell adapters to their semantics, so I can understand what went wrong at a high-level before I investigate the error specifically.
Currently, the
Microsoft.DSC/PowerShell
andMicrosoft.Windows/WindowsPowerShell
adapters only define exit codes0
(success) and1
(error).Proposed technical implementation details (optional)
Define reusable semantic exit codes for the adapter in
psDscAdapter.psm1
and use them in the adapter code.For example,
Then, when you need to use a specific exit code:
Then we could map the exit codes to their semantic meanings and reuse errors as needed. This proposal also includes the helper function
Write-JsonMessage
for sending a JSON Line back to DSC for debug, warnings, errors, etc.While out of scope for now, we should also consider whether and how to do i18n for exit codes and error messages. In this proposal I'm just matching the use of en-US already in place for the module and adapter.
The text was updated successfully, but these errors were encountered: