The following items are new for Chef Infra Client 12.2 and/or are changes from previous versions. The short version:

- **New dsc_resource** Use the **dsc_resource** resource to use any DSC resource in a Chef recipe.
- **New --exit-on-error option for knife-ssh** Use the `--exit-on-error` option to have the `knife ssh` subcommand exit on any error.

## dsc_resource

Windows PowerShell is a task-based command-line shell and scripting
language developed by Microsoft. Windows PowerShell uses a
document-oriented approach for managing Microsoft Windows-based
machines, similar to the approach that is used for managing Unix and
Linux-based machines. Windows PowerShell is [a tool-agnostic
platform](https://docs.microsoft.com/en-us/powershell/scripting/powershell-scripting)
that supports using Chef for configuration management.

Desired State Configuration (DSC) is a feature of Windows PowerShell
that provides [a set of language extensions, cmdlets, and
resources](https://docs.microsoft.com/en-us/powershell/dsc/overview)
that can be used to declaratively configure software. DSC is similar to
Chef, in that both tools are idempotent, take similar approaches to the
concept of resources, describe the configuration of a system, and then
take the steps required to do that configuration. The most important
difference between Chef and DSC is that Chef uses Ruby and DSC is
exposed as configuration data from within Windows PowerShell.

The **dsc_resource** resource allows any DSC resource to be used in a
Chef recipe, as well as any custom resources that have been added to
your Windows PowerShell environment. Microsoft [frequently adds new
resources](https://github.com/powershell/DscResources) to the DSC
resource collection.

Using the **dsc_resource** has the following requirements:

- Windows Management Framework (WMF) 5.0 February Preview (or higher),
    which includes Windows PowerShell 5.0.10018.0 (or higher).

- The `RefreshMode` configuration setting in the Local Configuration
    Manager must be set to `Disabled`.

    <div class="admonition-note">
    <p class="admonition-note-title">Note</p>
    <div class="admonition-note-text">

    Starting with Chef Infra Client 12.6 release, the `RefreshMode: Disabled`
    requirement applies only for versions of Windows PowerShell earlier
    than 5.0.10586.0. The latest version of Windows Management Framework
    (WMF) 5 has relaxed the limitation that prevented Chef Infra Client from
    running in non-disabled refresh mode.

    </div>
    </div>

- The **dsc_script** resource may not be used in the same run-list
    with the **dsc_resource**. This is because the **dsc_script**
    resource requires that `RefreshMode` in the Local Configuration
    Manager be set to `Push`, whereas the **dsc_resource** resource
    requires it to be set to `Disabled`.

- The **dsc_resource** resource can only use binary- or script-based
    resources. Composite DSC resources may not be used. This is because
    composite resources aren't "real" resources from the perspective of
    the Local Configuration Manager (LCM). Composite resources are used
    by the "configuration" keyword from the
    `PSDesiredStateConfiguration` module, and then evaluated in that
    context. When using DSC to create the configuration document (the
    Managed Object Framework (MOF) file) from the configuration command,
    the composite resource is evaluated. Any individual resources from
    that composite resource are written into the Managed Object
    Framework (MOF) document. As far as the Local Configuration Manager
    (LCM) is concerned, there is no such thing as a composite resource.
    Unless that changes, the **dsc_resource** resource and/or
    `Invoke-DscResource` command cannot directly use them.

### Syntax

A **dsc_resource** resource block allows DSC resources to be used in a
Chef recipe. For example, the DSC `Archive` resource:

```powershell
Archive ExampleArchive {
  Ensure = "Present"
  Path = "C:\Users\Public\Documents\example.zip"
  Destination = "C:\Users\Public\Documents\ExtractionPath"
}
```

and then the same **dsc_resource** with Chef:

```ruby
dsc_resource 'example' do
   resource :archive
   property :ensure, 'Present'
   property :path, "C:\Users\Public\Documents\example.zip"
   property :destination, "C:\Users\Public\Documents\ExtractionPath"
 end
```

The full syntax for all of the properties that are available to the
**dsc_resource** resource is:

```ruby
dsc_resource 'name' do
  module_name                String
  notifies                   # see description
  property                   Symbol
  resource                   String
  subscribes                 # see description
end
```

where

- `dsc_resource` is the resource
- `name` is the name of the resource block
- `property` is zero (or more) properties in the DSC resource, where
    each property is entered on a separate line, `:dsc_property_name` is
    the case-insensitive name of that property, and `"property_value"`
    is a Ruby value to be applied by the chef-client
- `module_name`, `property`, and `resource` are properties of this
    resource, with the Ruby type shown. See "Properties" section below
    for more information about all of the properties that may be used
    with this resource.

### Attributes

This resource has the following properties:

`ignore_failure`

:   **Ruby Type:** true, false | **Default Value:** `false`

    Continue running a recipe if a resource fails for any reason.

`module_name`

:   **Ruby Type:** String

    The name of the module from which a DSC resource originates. If this
    property is not specified, it will be inferred.

`notifies`

:   **Ruby Type:** Symbol, 'Chef::Resource\[String\]'

    A resource may notify another resource to take action when its state
    changes. Specify a `'resource[name]'`, the `:action` that resource
    should take, and then the `:timer` for that action. A resource may
    notify more than one resource; use a `notifies` statement for each
    resource to be notified.

    A timer specifies the point during Chef Infra Client run at which a
    notification is run. The following timers are available:

    `:delayed`

    :   Default. Specifies that a notification should be queued up, and
        then executed at the very end of Chef Infra Client run.

    `:immediate`, `:immediately`

    :   Specifies that a notification should be run immediately, per
        resource notified.

    The syntax for `notifies` is:

    ```ruby
    notifies :action, 'resource[name]', :timer
    ```

`property`

:   **Ruby Type:** Symbol

    A property from a Desired State Configuration (DSC) resource. Use
    this property multiple times, one for each property in the Desired
    State Configuration (DSC) resource. The format for this property
    must follow `property :dsc_property_name, "property_value"` for each
    DSC property added to the resource block.

    The `:dsc_property_name` must be a symbol.

    Use the following Ruby types to define `property_value`:

    <table>
    <colgroup>
    <col style="width: 50%" />
    <col style="width: 50%" />
    </colgroup>
    <thead>
    <tr class="header">
    <th>Ruby</th>
    <th>Windows PowerShell</th>
    </tr>
    </thead>
    <tbody>
    <tr>
    <td><code>Array</code></td>
    <td><code>Object[]</code></td>
    </tr>
    <tr>
    <td><code>Chef::Util::Powershell:PSCredential</code></td>
    <td><code>PSCredential</code></td>
    </tr>
    <tr>
    <td><code>False</code></td>
    <td><code>bool($false)</code></td>
    </tr>
    <tr>
    <td><code>Fixnum</code></td>
    <td><code>Integer</code></td>
    </tr>
    <tr>
    <td><code>Float</code></td>
    <td><code>Double</code></td>
    </tr>
    <tr>
    <td><code>Hash</code></td>
    <td><code>Hashtable</code></td>
    </tr>
    <tr>
    <td><code>True</code></td>
    <td><code>bool($true)</code></td>
    </tr>
    </tbody>
    </table>

    These are converted into the corresponding Windows PowerShell type
    during Chef Infra Client run.

`resource`

:   **Ruby Type:** String

    The name of the DSC resource. This value is case-insensitive and
    must be a symbol that matches the name of the DSC resource.

    For built-in DSC resources, use the following values:

    <table>
    <colgroup>
    <col style="width: 50%" />
    <col style="width: 50%" />
    </colgroup>
    <thead>
    <tr class="header">
    <th>Value</th>
    <th>Description</th>
    </tr>
    </thead>
    <tbody>
    <tr>
    <td><code>:archive</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/archiveresource">unpack archive (.zip) files</a>.</td>
    </tr>
    <tr>
    <td><code>:environment</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/environmentresource">manage system environment variables</a>.</td>
    </tr>
    <tr>
    <td><code>:file</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/fileresource">manage files and directories</a>.</td>
    </tr>
    <tr>
    <td><code>:group</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/groupresource">manage local groups</a>.</td>
    </tr>
    <tr>
    <td><code>:log</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/logresource">log configuration messages</a>.</td>
    </tr>
    <tr>
    <td><code>:package</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/packageresource">install and manage packages</a>.</td>
    </tr>
    <tr>
    <td><code>:registry</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/registryresource">manage registry keys and registry key values</a>.</td>
    </tr>
    <tr>
    <td><code>:script</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/scriptresource">run PowerShell script blocks</a>.</td>
    </tr>
    <tr>
    <td><code>:service</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/serviceresource">manage services</a>.</td>
    </tr>
    <tr>
    <td><code>:user</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/userresource">manage local user accounts</a>.</td>
    </tr>
    <tr>
    <td><code>:windowsfeature</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/windowsfeatureresource">add or remove Windows features and roles</a>.</td>
    </tr>
    <tr>
    <td><code>:windowsoptionalfeature</code></td>
    <td>Use to configure Microsoft Windows optional features.</td>
    </tr>
    <tr>
    <td><code>:windowsprocess</code></td>
    <td>Use to <a href="https://msdn.microsoft.com/en-us/powershell/dsc/windowsprocessresource">configure Windows processes</a>.</td>
    </tr>
    </tbody>
    </table>

    Any DSC resource may be used in a Chef recipe. For example, the DSC
    Resource Kit contains resources for [configuring Active Directory
    components](http://www.powershellgallery.com/packages/xActiveDirectory/2.8.0.0),
    such as `xADDomain`, `xADDomainController`, and `xADUser`. Assuming
    that these resources are available to the chef-client, the
    corresponding values for the `resource` attribute would be:
    `:xADDomain`, `:xADDomainController`, and `xADUser`.

`retries`

:   **Ruby Type:** Integer | **Default Value:** `0`

    The number of attempts to catch exceptions and retry the resource.

`retry_delay`

:   **Ruby Type:** Integer | **Default Value:** `2`

    The retry delay (in seconds).

`subscribes`

:   **Ruby Type:** Symbol, 'Chef::Resource\[String\]'

    A resource may listen to another resource, and then take action if
    the state of the resource being listened to changes. Specify a
    `'resource[name]'`, the `:action` to be taken, and then the `:timer`
    for that action.

    Note that `subscribes` does not apply the specified action to the
    resource that it listens to - for example:

    ```ruby
    file '/etc/nginx/ssl/example.crt' do
      mode '0600'
      owner 'root'
    end

    service 'nginx' do
      subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
    end
    ```

    In this case the `subscribes` property reloads the `nginx` service
    whenever its certificate file, located under
    `/etc/nginx/ssl/example.crt`, is updated. `subscribes` does not make
    any changes to the certificate file itself, it merely listens for a
    change to the file, and executes the `:reload` action for its
    resource (in this example `nginx`) when a change is detected.

    A timer specifies the point during Chef Infra Client run at which a
    notification is run. The following timers are available:

    `:delayed`

    :   Default. Specifies that a notification should be queued up, and
        then executed at the very end of Chef Infra Client run.

    `:immediate`, `:immediately`

    :   Specifies that a notification should be run immediately, per
        resource notified.

    The syntax for `subscribes` is:

    ```ruby
    subscribes :action, 'resource[name]', :timer
    ```

### Examples

**Open a Zip file**

```ruby
dsc_resource 'example' do
   resource :archive
   property :ensure, 'Present'
   property :path, 'C:\Users\Public\Documents\example.zip'
   property :destination, 'C:\Users\Public\Documents\ExtractionPath'
 end
```

**Manage users and groups**

```ruby
dsc_resource 'demogroupadd' do
  resource :group
  property :groupname, 'demo1'
  property :ensure, 'present'
end

dsc_resource 'useradd' do
  resource :user
  property :username, 'Foobar1'
  property :fullname, 'Foobar1'
  property :password, ps_credential('P@assword!')
  property :ensure, 'present'
end

dsc_resource 'AddFoobar1ToUsers' do
  resource :Group
  property :GroupName, 'demo1'
  property :MembersToInclude, ['Foobar1']
end
```