diff --git a/samples/json/tzutil/README.md b/samples/json/tzutil/README.md new file mode 100644 index 0000000..dea51a5 --- /dev/null +++ b/samples/json/tzutil/README.md @@ -0,0 +1,54 @@ +# Microsoft/tzutil + +## Introduction +The `Microsoft/tzutil` resource is a sample resources which allows you to manage time zone settings on Windows machines using DSC v3. This resource demonstrates that a resource may be made with a native binary that does not understand or outputs JSON. The JSON is merely made by wraping the command's input and output in PowerShell's `ConvertFrom-Json` and `ConvertTo-Json`. + +--- +***Note:*** +This methodology is not extremely extensible and should be avoided for most dsc resources. This example exists as a simple way to understand how the `*.dsc.resource.json` manifest interacts with a binary to create a dsc resource. DSC Resources should be either a native binary which understands and outputs json or a common tool which has a `-input json` or `-output json` flag (or something similar). + +--- + +## Prerequisites + +Before using the `Microsoft/tzutil` file, make sure you have the following prerequisites in place: +- DSC version 3 or later +- Windows Desktop or Server + +## Usage +To use the Microsoft/tzutil resource, follow these steps: + +1. Download the `Microsoft/tzutil` file from the official repository and save in the resource path for DSCv3 + +2. Create a yaml config called `tzutil.dsc.config.yaml` for the resource: + ```yaml + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + resources: + - name: Desired TimeZone + type: Microsoft/tzutil + properties: + timezone: UTC + dstoff: false + ``` + +3. Call the resource by piping the content to dsc: + ```powershell + cat .\tzutil.dsc.config.yaml | dsc config set + ``` + See the results: + ```yaml + results: + - name: Desired TimeZone + type: Microsoft/tzutil + result: + beforeState: + timezone: Pacific Standard Time + dstoff: false + afterState: + timezone: UTC + dstoff: false + changedProperties: + - timezone + messages: [] + hadErrors: false + ``` diff --git a/samples/json/tzutil/tzutil.dsc.config.yaml b/samples/json/tzutil/tzutil.dsc.config.yaml new file mode 100644 index 0000000..e99d989 --- /dev/null +++ b/samples/json/tzutil/tzutil.dsc.config.yaml @@ -0,0 +1,7 @@ +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +resources: +- name: Desired TimeZone + type: Microsoft/tzutil + properties: + timezone: UTC + dstoff: false \ No newline at end of file diff --git a/samples/json/tzutil/tzutil.dsc.resource.json b/samples/json/tzutil/tzutil.dsc.resource.json new file mode 100644 index 0000000..b8a0f7b --- /dev/null +++ b/samples/json/tzutil/tzutil.dsc.resource.json @@ -0,0 +1,114 @@ +{ + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json", + "type": "Microsoft/tzutil", + "version": "0.0.1", + "description": "Windows Time Zone Utility", + "tags": ["timezone","example"], + "get": { + "executable": "powershell", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "$value = tzutil.exe /g;", + "$v= if($value -match '_dstoff'){ $true } else { $false};", + "[ordered]@{'timezone'=$value; 'dstoff' = $v} | ConvertTo-Json -Compress" + ], + "return": "state" + }, + "set": { + "executable": "powershell", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "$value = ($Input | ConvertFrom-Json);", + "$v= if($value.dstoff){\"$($value.timezone)_dstoff\"} else {\"$($value.timezone)\"};", + "tzutil.exe /s \"$v\";", + "$value = tzutil.exe /g;", + "$v= if($value -match '_dstoff'){ $true } else { $false};", + "[ordered]@{'timezone'=$value; 'dstoff' = $v} | ConvertTo-Json -Compress" + ], + "implementsPretest": false, + "return": "state", + "input": "stdin" + }, + "test":{ + "executable": "powershell", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "$value = tzutil.exe /g;", + "$v= if($value -match '_dstoff'){ $true } else { $false};", + "[ordered]@{'timezone'=$value; 'dstoff' = $v} | ConvertTo-Json -Compress" + ], + "return": "state", + "input": "stdin" + }, + "export":{ + "executable": "powershell", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "$value = tzutil.exe /g;", + "$v= if($value -match '_dstoff'){ $true } else { $false};", + "[ordered]@{'timezone'=$value; 'dstoff' = $v} | ConvertTo-Json -Compress" + ] + }, + "exitCodes": { + "0": "Success", + "1": "Error" + }, + "schema": { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "tzutil", + "type": "object", + "required": [ + "timezone" + ], + "additionalProperties": false, + "properties": { + "timezone" : {"$ref": "#/definitions/Timezone"}, + "dstoff": {"type": "boolean"} + }, + "definitions": { + "Timezone": {"type":"string", + "title": "timezone", + "description": "Defines the timezone", + "enum": ["Dateline Standard Time","UTC-11","Aleutian Standard Time","Hawaiian Standard Time", + "Marquesas Standard Time","Alaskan Standard Time","UTC-09","Pacific Standard Time (Mexico)","UTC-08","Pacific Standard Time", + "US Mountain Standard Time","Mountain Standard Time (Mexico)","Mountain Standard Time","Yukon Standard Time","Central America Standard Time", + "Central Standard Time","Easter Island Standard Time","Central Standard Time (Mexico)","Canada Central Standard Time","SA Pacific Standard Time", + "Eastern Standard Time (Mexico)","Eastern Standard Time","Haiti Standard Time","Cuba Standard Time","US Eastern Standard Time", + "Turks And Caicos Standard Time","Paraguay Standard Time","Atlantic Standard Time","Venezuela Standard Time","Central Brazilian Standard Time", + "SA Western Standard Time","Pacific SA Standard Time","Newfoundland Standard Time","Tocantins Standard Time","E. South America Standard Time", + "SA Eastern Standard Time","Argentina Standard Time","Montevideo Standard Time","Magallanes Standard Time","Saint Pierre Standard Time","Bahia Standard Time", + "UTC-02","Greenland Standard Time","Azores Standard Time","Cape Verde Standard Time","UTC","GMT Standard Time","Greenwich Standard Time", + "Sao Tome Standard Time","Morocco Standard Time","W. Europe Standard Time","Central Europe Standard Time","Romance Standard Time","Central European Standard Time", + "W. Central Africa Standard Time","GTB Standard Time","Middle East Standard Time","Egypt Standard Time","E. Europe Standard Time", + "West Bank Standard Time","South Africa Standard Time","FLE Standard Time","Israel Standard Time","South Sudan Standard Time", + "Kaliningrad Standard Time","Sudan Standard Time","Libya Standard Time","Namibia Standard Time","Jordan Standard Time","Arabic Standard Time", + "Syria Standard Time","Turkey Standard Time","Arab Standard Time","Belarus Standard Time","Russian Standard Time","E. Africa Standard Time", + "Volgograd Standard Time","Iran Standard Time","Arabian Standard Time","Astrakhan Standard Time","Azerbaijan Standard Time","Russia Time Zone 3", + "Mauritius Standard Time","Saratov Standard Time","Georgian Standard Time","Caucasus Standard Time","Afghanistan Standard Time", + "West Asia Standard Time","Ekaterinburg Standard Time","Pakistan Standard Time","Qyzylorda Standard Time","India Standard Time", + "Sri Lanka Standard Time","Nepal Standard Time","Central Asia Standard Time","Bangladesh Standard Time","Omsk Standard Time","Myanmar Standard Time", + "SE Asia Standard Time","Altai Standard Time","W. Mongolia Standard Time","North Asia Standard Time","N. Central Asia Standard Time", + "Tomsk Standard Time","China Standard Time","North Asia East Standard Time","Singapore Standard Time","W. Australia Standard Time", + "Taipei Standard Time","Ulaanbaatar Standard Time","Aus Central W. Standard Time","Transbaikal Standard Time","Tokyo Standard Time", + "North Korea Standard Time","Korea Standard Time","Yakutsk Standard Time","Cen. Australia Standard Time","AUS Central Standard Time", + "E. Australia Standard Time","AUS Eastern Standard Time","West Pacific Standard Time","Tasmania Standard Time","Vladivostok Standard Time", + "Lord Howe Standard Time","Bougainville Standard Time","Russia Time Zone 10","Magadan Standard Time","Norfolk Standard Time","Sakhalin Standard Time", + "Central Pacific Standard Time","Russia Time Zone 11","New Zealand Standard Time","UTC+12","Fiji Standard Time","Chatham Islands Standard Time", + "UTC+13","Tonga Standard Time","Samoa Standard Time","Line Islands Standard Time"]} + } + } + } +} \ No newline at end of file