mirror of https://github.com/microsoft/PowerToys.git synced 2026-04-03 09:46:54 +02:00

Files

Gijs Reijn 3b6453c932 Improve DSC documentation (#42554 )

<!-- Enter a brief description/summary of your PR here. What does it
fix/what does it change/how was it tested (even manually, if necessary)?
-->
## Summary of the Pull Request

This documentation enhances the DSC documentation by incorporating
reference documents and providing examples.

Closes #42552.

<!-- Please review the items on the PR checklist before submitting-->
## PR Checklist

- [x] Closes: #xxx
- [ ] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [ ] **Tests:** Added/updated and all pass
- [ ] **Localization:** All end-user-facing strings can be localized
- [ ] **Dev docs:** Added/updated
- [ ] **New binaries:** Added on the required places
- [ ] [JSON for
signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json)
for new binaries
- [ ] [WXS for
installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs)
for new binaries and localization folder
- [ ] [YML for CI
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml)
for new test projects
- [ ] [YML for signed
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml)
- [ ] **Documentation updated:** If checked, please file a pull request
on [our docs
repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys)
and link it here: #xxx

<!-- Provide a more detailed description of the PR, other things fixed,
or any additional comments/features here -->
## Detailed Description of the Pull Request / Additional comments

<!-- Describe how you validated the behavior. Add automated tests
wherever possible, but list manual validation steps taken as well -->
## Validation Steps Performed

---------

Co-authored-by: Niels Laute <niels.laute@live.nl>

2026-04-01 16:56:40 +08:00

4.4 KiB

Raw Blame History

description, ms.date, ms.topic, title

description	ms.date	ms.topic	title
DSC configuration reference for PowerToys Hosts module	10/18/2025	reference	Hosts Module

Hosts Module

Synopsis

Manages configuration for the Hosts File Editor utility, a quick editor for the Windows hosts file.

Description

The Hosts module configures PowerToys Hosts File Editor, a utility that provides a user-friendly interface for viewing and editing the Windows hosts file. It simplifies the process of adding, modifying, and managing DNS entries in the hosts file.

Properties

The Hosts module supports the following configurable properties:

LaunchAdministrator

Controls whether the Hosts File Editor launches with administrator privileges by default.

Type: boolean
Default: false
Description: When enabled, the editor will always attempt to launch with elevated permissions, which is required to edit the hosts file.

LoopbackDuplicates

Controls how duplicate loopback addresses are handled.

Type: boolean
Default: false

AdditionalLinesPosition

Controls where additional lines are positioned when editing entries.

Type: integer
Allowed values:

0 - Top
1 - Bottom

Default: 0

Examples

Example 1 - Enable admin launch with direct execution

This example configures the Hosts editor to always launch with admin rights.

$config = @{
    settings = @{
        properties = @{
            LaunchAdministrator = $true
        }
        name = "Hosts"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe set --resource 'settings' --module Hosts --input $config

Example 2 - Configure with DSC

This example enables administrator launch and configures line positioning.

dsc config set --file hosts-config.dsc.yaml

# hosts-config.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure Hosts File Editor
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
          AdditionalLinesPosition: 1
        name: Hosts
        version: 1.0

Example 3 - Install and configure with WinGet

This example installs PowerToys and configures the Hosts editor for admin launch.

winget configure winget-hosts.yaml

# winget-hosts.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
metadata:
  winget:
    processor: dscv3
resources:
  - name: Install PowerToys
    type: Microsoft.WinGet.DSC/WinGetPackage
    properties:
      id: Microsoft.PowerToys
      source: winget
  
  - name: Configure Hosts File Editor
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
          LoopbackDuplicates: false
        name: Hosts
        version: 1.0

Example 4 - Development configuration

This example configures for development use with new entries at the bottom.

dsc config set --file hosts-development.dsc.yaml

# hosts-development.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Development hosts configuration
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
          AdditionalLinesPosition: 1
        name: Hosts
        version: 1.0

Use cases

System administration

Configure for frequent hosts file editing:

resources:
  - name: Admin configuration
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
        name: Hosts
        version: 1.0

Web development

Configure for development environment management:

resources:
  - name: Developer configuration
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
          AdditionalLinesPosition: 1
        name: Hosts
        version: 1.0

4.4 KiB Raw Blame History