Forgot to commit

Author: Gijsreyn

docs/reference/resources/Microsoft/adapter/powershell/index.md

@@ -85,7 +85,7 @@ You can directly call the adapter script to clear the cache with the **Operation
 set to `ClearCache`:
 
 ```powershell
-$adapterScript = dsc resource list -a Microsoft.Adapter/PowerShell |
+$adapterScript = dsc resource list Microsoft.Adapter/PowerShell |
     ConvertFrom-Json |
     Select-Object -ExpandProperty directory |
     Join-Path -ChildPath 'psDscAdapter' -AdditionalChildPath 'powershell.resource.ps1'

docs/reference/resources/Microsoft/adapter/windowspowershell/index.md

@@ -20,18 +20,26 @@ Tags:               [windows, powershell]
 Executable:         powershell
 ```
 
-## Instance definition syntax
+## Adapted resource instance definition syntax
 
-> [!NOTE]
-> The `directives.requireAdapter` syntax is available in DSC 3.2 and later.
+### Implicitly required adapter syntax
+
+```yaml
+- name: <instance name>
+  type: <module name>/<resource name>
+  properties: # adapted resource properties
+    <property name>: <property value>
+```
+
+### Explicitly required adapter syntax
 
 ```yaml
-resources:
 - name: <instance name>
   type: <module name>/<resource name>
+  properties: # adapted resource properties
+    <property name>: <property value>
   directives:
     requireAdapter: Microsoft.Adapter/WindowsPowerShell
-  properties: # adapted resource properties
 ```
 
 ## Description
@@ -45,19 +53,22 @@ State Configuration (PSDSC) resources in DSC. The resource can:
 
 The adapter manages the PSDSC resources in Windows PowerShell (powershell.exe), not PowerShell
 (pwsh). To use class-based PSDSC resources in PowerShell, use the
-[Microsoft.Adapter/PowerShell](../powershell/index.md) adapter.
+[Microsoft.Adapter/PowerShell][01] adapter.
 
 This adapter uses the **PSDesiredStateConfiguration** module v1.1. This module is built-in when
 you install Windows and is located in
 `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules`.
 
 > [!NOTE]
-> This adapter replaces the deprecated
-> [Microsoft.Windows/WindowsPowerShell](../../Windows/WindowsPowerShell/index.md) adapter. In
-> earlier versions of DSC, adapted resources were nested inside a parent adapter resource using
+> This adapter replaces the deprecated [Microsoft.Windows/WindowsPowerShell][02] adapter.
+>
+> In earlier versions of DSC, adapted resources were nested inside a parent adapter resource using
 > the `properties.resources` array. Starting in DSC 3.2, each adapted resource is listed directly
-> in the configuration document's `resources` array with `directives.requireAdapter` set to
-> `Microsoft.Adapter/WindowsPowerShell`.
+> in the configuration document's `resources` array.
+>
+> You can use the [`requireAdapter` directive][03] to explicitly indicate that the instance should
+> use this adapter. When you don't specify the `requireAdapter` directive, DSC invokes the adapted
+> resource through the first adapter that indicates it can invoke the resource.
 
 ### PowerShell resource adapter cache
 
@@ -97,96 +108,82 @@ $adapterScript = dsc resource list Microsoft.Adapter/WindowsPowerShell |
 ## Requirements
 
 - This adapter is only available on Windows.
-- The process context must have appropriate permissions for the DSC resources to be executed.
-- PowerShell modules exposing DSC resources should be installed in one of the following locations:
+- The process security context must be elevated.
+
+  For PSDSC 1.1, invoking DSC resources requires the process to run as Administrator. Attempting to
+  invoke the resources in a non-elevated context fails.
+- Windows PowerShell Desired State Configuration (PSDSC) depends on WinRM. If WinRM isn't setup on
+  the machine, invoking PSDSC resources through the adapter will raise an error.
+
+  You can use the [`Enable-PSRemoting` cmdlet][04] in an elevated Windows PowerShell session to
+  enable WinRM.
+- PowerShell modules exposing PSDSC resources for use with this adapter must be installed in one of
+  the following locations:
+
   - `%PROGRAMFILES%\WindowsPowerShell\Modules`
   - `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules`
 
+  PSDSC 1.1 only finds PSDSC resources when the module containing them is installed in the machine
+  scope. Modules containing PSDSC resources in the user scope or another non-default location
+  aren't recognized by PSDSC 1.1 and can't be invoked through this adapter.
+
 ## Capabilities
 
 The resource adapter has the following capabilities:
 
-- `get` - Retrieve the actual state of a DSC resource instance.
-- `set` - Enforce the desired state for a DSC resource instance.
-- `test` - Determine whether a DSC resource instance is in the desired state.
-- `export` - Discover and enumerate DSC resource instances available on the system.
-- `list` - List available Windows PowerShell DSC resources that can be used with `dsc.exe`.
+- `get` - Retrieve the actual state of an adapted DSC resource instance.
+- `set` - Enforce the desired state for an adapted DSC resource instance.
+- `test` - Determine whether an adapted DSC resource instance is in the desired state.
+- `export` - Discover and enumerate adapted DSC resource instances available on the system.
+- `list` - List available Windows PowerShell DSC resources that can be used as adapted DSC
+  resources.
 
 > [!NOTE]
-> The `export` capability is only available with class-based DSC resources. Script-based and
-> binary DSC resources don't support the export operation.
+> The `export` capability is only available for class-based PSDSC resources. Script-based and
+> binary PSDSC resources don't support the export operation.
 
 ## Examples
 
-- [Manage a Windows service with the WindowsPowerShell adapter][02]
+- [Manage a Windows service with the WindowsPowerShell adapter][05]
 
 ## Adapted resource instances
 
-Adapted resource instances are listed directly in the configuration document's `resources` array.
-Set `directives.requireAdapter` to `Microsoft.Adapter/WindowsPowerShell` to indicate that DSC
-should use this adapter to invoke the instance. This feature requires DSC 3.2 or later.
+Define adapted resource instances directly in the configuration document's `resources` array.
 
-Every adapted instance must be an object that defines the [name](#adapted-instance-name),
-[type](#adapted-instance-type), and [properties](#adapted-instance-properties) for the instance.
+To explicitly indicate that DSC should use this adapter for the resource instance, define the
+`requireAdapter` directive as `Microsoft.Adapter/WindowsPowerShell`. When you don't specify the
+`requireAdapter` directive, DSC invokes the adapted resource through the first adapter that
+indicates it can invoke the resource.
 
-### Adapted instance name
+Adapted resource instances are defined identically to non-adapted resource instances in a
+configuration document with the following exceptions:
 
-The `name` property of the adapted resource instance defines the short, human-readable name for the
-instance. The adapted instance name must be a non-empty string containing only letters, numbers,
-and spaces. This property must be unique within the configuration document's `resources` array.
+1. The fully qualified type name (`type` field) for the adapted instance is defined by the adapter.
+   This adapter uses the following syntax for determining the fully qualified type name of a PSDSC
+   resource:
 
-```yaml
-PropertyName:  name
-Type:          string
-Required:      true
-MinimumLength: 1
-Pattern:       ^[a-zA-Z0-9 ]+$
-```
-
-### Adapted instance type
-
-The `type` property identifies the adapted instance's PSDSC resource. The value for this property
-must be the valid fully qualified type name for the resource.
-
-This adapter uses the following syntax for determining the fully qualified type name of a PSDSC
-resource:
-
-```Syntax
-<module name>/<resource name>
-```
+   ```Syntax
+   <module name>/<resource name>
+   ```
 
-For example, if a PowerShell module named **TailspinToys** has a script-based PSDSC resource named
-`TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`.
+   For example, if a PowerShell module named **TailspinToys** has a script-based PSDSC resource named
+   `TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`.
 
-For more information about type names in DSC, see
-[DSC Resource fully qualified type name schema reference][01].
+   For more information about type names in DSC, see
+   [DSC Resource fully qualified type name schema reference][06].
 
-```yaml
-Type:     string
-Required: true
-Pattern:  ^\w+(\.\w+){0,2}\/\w+$
-```
-
-### Adapted instance properties
-
-The `properties` of an adapted resource instance define its desired state. The value of this
-property must be an object. The specified properties are validated at runtime when the adapter
-tries to invoke the adapted PSDSC resource instance. This adapter doesn't support static linting
-for adapted instance properties in a configuration document.
+1. The `properties` field for the instance is validated at runtime when the adapter tries to invoke
+   the adapted PSDSC resource instance. This adapter doesn't support static linting for adapted
+   instance properties in a configuration document.
 
-Each name for each property must be a configurable property of the PSDSC resource. The property
-name isn't case sensitive. The value for each property must be valid for that property. If you
-specify an invalid property name or value, the adapter raises an error when it tries to invoke the
-resource.
-
-```yaml
-Type:     object
-Required: true
-```
+   Each property name must be a configurable property of the PSDSC resource. The property name
+   isn't case sensitive. The value for each property must be valid for that property. If you
+   specify an invalid property name or value, the adapter raises an error when it tries to invoke
+   the resource.
 
 ## Exit codes
 
-The resource returns the following exit codes from operations:
+The adapter resource returns the following exit codes from operations:
 
 - [0](#exit-code-0) - Success
 - [1](#exit-code-1) - Error
@@ -203,9 +200,13 @@ an error message with details about the failure.
 
 ## See also
 
-- [Microsoft.Adapter/PowerShell](../powershell/index.md)
-- [Microsoft.Windows/WindowsPowerShell](../../Windows/WindowsPowerShell/index.md) (deprecated)
+- [Microsoft.Adapter/PowerShell][01]
+- [Microsoft.Windows/WindowsPowerShell][02] (deprecated)
 
 <!-- Link references -->
-[01]: ../../../../concepts/type-names.md
-[02]: examples/manage-a-windows-service.md
+[01]: ../powershell/index.md
+[02]: ../../Windows/WindowsPowerShell/index.md
+[03]: ../../../../schemas/config/resource.md#requireAdapter
+[04]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/enable-psremoting?view=powershell-5.1&preserveView=true
+[05]: examples/manage-a-windows-service.md
+[06]: ../../../../schemas/definitions/resourceType.md