Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Implement export Windows PowerShell adapter#848

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes from5 commits
Commits
Show all changes
13 commits
Select commitHold shift + click to select a range
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
---
description: >
Examples showing how you can invoke the Microsoft.Windows/WindowsPowerShell with DSC to manage
a Windows service using the PSDesiredStateConfiguration module.

ms.date: 03/25/2025
ms.topic: reference
title: Manage a Windows service
---

This example shows how you can use the `Microsoft.Windows/WindowsPowerShell` resource with the `PSDesiredStateConfiguration` module to manage a Windows service.
These examples manage the `Spooler` print spooler service.

> [!NOTE]
> Run this example in an elevated PowerShell session with `dsc.exe` version 3.1.0-preview.2 or later.

## Test whether a service is running

The following snippet shows how you can use the resource with the [dsc resource test][01] command to check whether the `Spooler` service is running.

```powershell
$instance = @{
Name = 'Spooler'
StartupType = 'Automatic'
} | ConvertTo-Json

dsc resource test --resource PSDesiredStateConfiguration/Service --input $instance
```

When the service isn't running or has a different startup type, DSC returns the following result:

```yaml
desiredState:
Name: Spooler
StartupType: Manual
actualState:
InDesiredState: false
inDesiredState: false
differingProperties:
- StartupType
```

The `inDesiredState` field of the result object is set to `false`, indicating that the instance isn't in the desired state. The `differingProperties` field indicates that the `property` property is mismatched between the desired state and actual state.

## Ensure a service is running with automatic startup

To set the system to the desired state and configure the service, use the [dsc resource set][02] command.

```powershell
dsc resource set --resource PSDesiredStateConfiguration/Service --input $instance
```

When the resource configures the service, DSC returns the following result:

```yaml
beforeState:
Status: null /
Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
DisplayName: Print Spooler
ResourceId: null
PsDscRunAsCredential: null
Name: Spooler
Credential: null
PSComputerName: localhost
ConfigurationName: null
Ensure: null
DependsOn: null
SourceInfo: null
BuiltInAccount: LocalSystem
StartupType: Manual
State: Running
ModuleVersion: '1.1'
ModuleName: PSDesiredStateConfiguration
Path: C:\WINDOWS\System32\spoolsv.exe
Dependencies:
- RPCSS
- http
afterState:
Status: null
Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
DisplayName: Print Spooler
ResourceId: null
PsDscRunAsCredential: null
Name: Spooler
Credential: null
PSComputerName: localhost
ConfigurationName: null
Ensure: null
DependsOn: null
SourceInfo: null
BuiltInAccount: LocalSystem
StartupType: Automatic
State: Running
ModuleVersion: '1.1'
ModuleName: PSDesiredStateConfiguration
Path: C:\WINDOWS\System32\spoolsv.exe
Dependencies:
- RPCSS
- http
changedProperties:
- StartupType
```

You can test the instance again to confirm that the service is configured correctly:

```powershell
dsc resource test --resource PSDesiredStateConfiguration/Service --input $instance
```

```yaml
desiredState:
Name: Spooler /
StartupType: Manual
actualState:
InDesiredState: true
inDesiredState: true
differingProperties: []
```

## Stop a service

The following snippet shows how you can configure the `Spooler` service to be stopped with manual startup.

```powershell
$stopInstance = @{
Name = 'Spooler'
State = 'Stopped'
StartupType = 'Manual'
} | ConvertTo-Json

dsc resource set --resource PSDesiredStateConfiguration/Service --input $stopInstance
```

When the resource stops the service, DSC returns the following result:

```yaml
beforeState:
Status: null /
Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
DisplayName: Print Spooler
ResourceId: null
PsDscRunAsCredential: null
Name: Spooler
Credential: null
PSComputerName: localhost
ConfigurationName: null
Ensure: null
DependsOn: null
SourceInfo: null
BuiltInAccount: LocalSystem
StartupType: Manual
State: Running
ModuleVersion: '1.1'
ModuleName: PSDesiredStateConfiguration
Path: C:\WINDOWS\System32\spoolsv.exe
Dependencies:
- RPCSS
- http
afterState:
Status: null
Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
DisplayName: Print Spooler
ResourceId: null
PsDscRunAsCredential: null
Name: Spooler
Credential: null
PSComputerName: localhost
ConfigurationName: null
Ensure: null
DependsOn: null
SourceInfo: null
BuiltInAccount: LocalSystem
StartupType: Manual
State: Stopped
ModuleVersion: '1.1'
ModuleName: PSDesiredStateConfiguration
Path: C:\WINDOWS\System32\spoolsv.exe
Dependencies:
- RPCSS
- http
changedProperties:
- State
```

## Verify the current state of a service

To check the current state of the service, use the `dsc resource get` command.

```powershell
dsc resource get --resource PSDesiredStateConfiguration/Service --input $instance
```

```yaml
actualState:
Status: null /
Description: This service spools print jobs and handles interaction with the printer. If you turn off this service, you won't be able to print or see your printers.
DisplayName: Print Spooler
ResourceId: null
PsDscRunAsCredential: null
Name: Spooler
Credential: null
PSComputerName: localhost
ConfigurationName: null
Ensure: null
DependsOn: null
SourceInfo: null
BuiltInAccount: LocalSystem
StartupType: Manual
State: Stopped
ModuleVersion: '1.1'
ModuleName: PSDesiredStateConfiguration
Path: C:\WINDOWS\System32\spoolsv.exe
Dependencies:
- RPCSS
- http
```

## Restore the original service configuration

If you want to restore the service to its original running state, you can reapply the first configuration.

```powershell
dsc resource set --resource Microsoft.Windows/WindowsPowerShell --input $instance
```

<!-- Link reference definitions -->
[01]: ../../../../../cli/resource/test.md
[02]: ../../../../../cli/resource/set.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
---
description: Microsoft.Windows/WindowsPowerShell resource adapter reference documentation
ms.date: 03/25/2025
ms.topic: reference
title: Microsoft.Windows/WindowsPowerShell
---

# Microsoft.Windows/WindowsPowerShell

## Synopsis

Manage PowerShell DSC resources. This adapter enables you to use class-based, script-based, or binary PowerShell DSC resources available on the system.

## Metadata

```yaml
Version : 0.1.0
Kind : resource
Tags : [Windows]
Author : Microsoft
```

## Instance definition syntax

```yaml
resources:
- name: <instanceName>
type: Microsoft.Windows/WindowsPowerShell
properties:
resources:
- name: <instanceName>
type: <moduleName>/<resourceName>
properties:
# Instance properties
Ensure: Present

# Or from v3.1.0-preview.2 onwards
resources:
- name: <instanceName>
type: <moduleName>/<resourceName>
properties:
# Instance properties
Ensure: Present
```

## Description

The `Microsoft.Windows/WindowsPowerShell` resource adapter enables you to invoke PSDSC resources. The resource can:

- Execute script-based DSC resources
- Run class-based DSC resource methods
- Execute binary DSC resources

> [!NOTE]
> This resource is installed with DSC itself on Windows systems.
>
> You can update this resource by updating DSC. When you update DSC, the updated version of this
> resource is automatically available.

## Requirements

- The resource is only usable on a Windows system.
- The resource must run in a process context that has appropriate permissions for the DSC resource to be executed.
- The PowerShell modules exposing DSC resources should be installed in
`%PROGRAMFILES%\WindowsPowerShell\Modules` or
`%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules`

## Capabilities

The resource adapter has the following capabilities:

- `get` - You can use the resource to retrieve the actual state of a DSC resource instance.
- `set` - You can use the resource to enforce the desired state for a DSC resource instance.
- `test` - You can use the resource to determine whether a DSC resource instance is in the desired state.
- `export` - You can use the resource to discover and enumerate DSC resource instances currently installed and available on the system.
- `list` - Lists available PowerShell DSC resources on your system that can be used with `dsc.exe`.

> [!NOTE]
> The `export` capability is only available with class-based DSC resources.
> Script-based and binary DSC resources do not support the export operation.

## Examples

1. [Manage a Windows Service][01] - Shows how to manage a Windows service

## Properties

Unlike standard resources, the `Microsoft.Windows/WindowsPowerShell` resource adapter doesn't have directly exposed properties
in its schema because it acts as a bridge to PowerShell DSC resource. Instead, the adapter:

1. Dynamically discovers the property schema for each PowerShell DSC resource
2. Stores the schema properties in a cache file for improved performance in subsequent operations
3. Passes properties to the underlying PowerShell DSC resource

The adapter maintains a cache of resource schemas at:

- Windows: `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json`

To list the schema properties for a PowerShell DSC resource, you can run the following command:

```powershell
dsc resource list --adapter Microsoft.Windows/WindowsPowerShell <moduleName>/<resourceName> |
ConvertFrom-Json |
Select-Object properties
```

You can also retrieve more information by directly reading it from the cache file:

```powershell
$cache = Get-Content -Path "$env:LOCALAPPDATA\dsc\WindowsPSAdapterCache.json" |
ConvertFrom-Json

($cache.ResourceCache | Where-Object -Property type -EQ '<moduleName>/<resourceName>').DscResourceInfo.Properties
```

## Exit codes

The resource returns the following exit codes from operations:

- [0](#exit-code-0) - Success
- [1](#exit-code-1) - Error

### Exit code 0

Indicates the resource operation completed without errors.

### Exit code 1

Indicates the resource operation failed because the underlying DSC resource method or Invoke-DscResource call did not succeed.
When the resource returns this exit code, it also emits an error message with details about the failure.

<!-- Link definitions -->
[01]: ./examples/manage-a-windows-service.md
[8]ページ先頭
©2009-2025 Movatter.jp