hostsfileeditor.md
1 # Hosts File Editor 2 3 [Public overview - Microsoft Learn](https://learn.microsoft.com/en-us/windows/powertoys/hosts-file-editor) 4 5 ## Quick Links 6 7 [All Issues](https://github.com/microsoft/PowerToys/issues?q=is%3Aopen%20label%3A%22Product-Hosts%20File%20Editor%22)<br> 8 [Bugs](https://github.com/microsoft/PowerToys/issues?q=is%3Aopen%20label%3A%22Product-Hosts%20File%20Editor%22%20label%3AIssue-Bug)<br> 9 [Pull Requests](https://github.com/microsoft/PowerToys/pulls?q=is%3Apr+is%3Aopen+label%3A%22Product-Hosts+File+Editor%22) 10 11 ## Overview 12 13 The Hosts File Editor module provides a convenient way to edit the system's hosts file. The hosts file is a plain text file used by the operating system to map hostnames to IP addresses, allowing users to override DNS for specific domain names. 14 15 ## Code Structure 16 17  18 19 The Hosts File Editor module is structured into three primary components: 20 21 1. **Hosts** - Entry point for the Hosts File Editor. Manages core services and settings through helper utilities. 22 2. **HostsModuleInterface** - Interface for integrating the Hosts module with the PowerToys system. 23 3. **HostsUILib** - Implements the UI layer using WinUI 3. 24 25 This structure is similar to the Environment Variables for Windows module. 26 27 ## Key Components 28 29 ### Main Entry Points 30 31 - **Module Entry**: [Program.cs](/src/modules/Hosts/Program.cs) → [App.xaml.cs](/src/modules/Hosts/HostsXAML/App.xaml.cs) 32 - **Settings UI**: 33 - Main Window: [MainWindow.xaml.cs](/src/modules/Hosts/Hosts/HostsXAML/MainWindow.xaml.cs) 34 - View: [HostsMainPage.xaml](/src/modules/Hosts/HostsUILib/HostsMainPage.xaml) 35 - ViewModel: [HostsMainPage.xaml.cs](/src/modules/Hosts/HostsUILib/HostsMainPage.xaml.cs) 36 - **Runner Integration**: [HostsModuleInterface](/src/modules/Hosts/HostsModuleInterface) 37 38 ### Runner Integration 39 40 The module is loaded by the PowerToys runner from: 41 - [main.cpp](/src/runner/main.cpp) (Lines 183-184): Loads Hosts Module using `L"WinUI3Apps/PowerToys.HostsModuleInterface.dll"` 42 43 ### Settings Management 44 45 - [HostsViewModel.cs](/src/settings-ui/Settings.UI/ViewModels/HostsViewModel.cs): Hosts UI in PowerToys settings 46 - [HostsProperties.cs](/src/settings-ui/Settings.UI.Library/HostsProperties.cs): In settings UI 47 - [HostsSettings.cs](/src/settings-ui/Settings.UI.Library/HostsSettings.cs): Wrapper with HostsProperties 48 49 ### Module Components 50 51 #### HostsModuleInterface 52 53 - Defines the interface for integrating the Hosts module with the PowerToys system. 54 55 #### Hosts (Main Project) 56 57 - [Program.cs](/src/modules/Hosts/Hosts/Program.cs): Launch app 58 - [HostsXAML](/src/modules/Hosts/Hosts/HostsXAML): Initialize service and loads the main window 59 - [Host.cs](/src/modules/Hosts/Hosts/Helpers/Host.cs): Access to services register 60 - [NativeEventWaiter.cs](/src/modules/Hosts/Hosts/Helpers/NativeEventWaiter.cs): Gets the dispatcher queue for posting UI updates from a background thread 61 - [UserSettings.cs](/src/modules/Hosts/Hosts/Settings/UserSettings.cs): Manages reading, tracking, and updating user settings from settings.json 62 63 #### HostsUILib 64 65 - [HostsMainPage.xaml.cs](/src/modules/Hosts/HostsUILib/HostsMainPage.xaml.cs): Main page 66 - [ViewModels](/src/modules/Hosts/HostsUILib/ViewModels): Contains view models that manage state and logic 67 - [Models](/src/modules/Hosts/HostsUILib/Models): Models for managing host entries 68 - [AddressType.cs](/src/modules/Hosts/HostsUILib/Models/AddressType.cs): Specifies whether an address is IPv4, IPv6, or Invalid 69 - [Entry.cs](/src/modules/Hosts/HostsUILib/Models/Entry.cs): Represents a single hosts file entry (IP address, hostnames, comment, flags) 70 - [HostsData.cs](/src/modules/Hosts/HostsUILib/Models/HostsData.cs): Converts the list of entries into a read-only collection 71 - [Settings](/src/modules/Hosts/HostsUILib/Settings): Settings configuration 72 - [Consts.cs](/src/modules/Hosts/HostsUILib/Consts.cs): Defines constants like max hosts IP length 73 - [Helpers](/src/modules/Hosts/HostsUILib/Helpers): Utilities for dealing with hosts IP, filter features, and file loading 74 75 ## Call Flow 76 77 1. **Enable app**: runner/main.cpp → settings.ui/settings.ui.library 78 2. **Start app**: Program.cs → HostsXAML → HostsMainPage 79 3. **Load hosts data**: ViewModel → HostsData → Helpers (load and parse file) 80 4. **User edits**: UI bound to ViewModel updates entries 81 5. **Save changes**: ViewModel triggers file write through Helpers 82 6. **Settings management**: UserSettings.cs persists user preferences 83 84 ## Key Features 85 86 | Feature | Key Function | 87 |---------|--------------| 88 | Adding a new entry | `Add(Entry entry)` | 89 | Filtering host file entries | `ApplyFilters()` | 90 | Open Hosts File | `ReadHosts()` | 91 | Additional Lines | `UpdateAdditionalLines(string lines)` | 92 93 ## Settings 94 95 | Setting | Implementation | 96 |---------|---------------| 97 | Open as administrator | `UserSettings()` | 98 | Additional lines position | `UserSettings()->AdditionalLinesPosition` | 99 | Consider loopback addresses as duplicates | `UserSettings()->LoopbackDuplicates` | 100 | Encoding Setting | `UserSettings()->Encoding` | 101 102 ## UI Test Automation 103 104 Hosts File Editor is currently undergoing a UI Test migration process to improve automated testing coverage. You can track the progress of this migration at: 105 106 [Hosts File Editor UI Test Migration Progress](https://github.com/microsoft/PowerToys/blob/feature/UITestAutomation/src/modules/Hosts/Hosts.UITests/Release-Test-Checklist-Migration-Progress.md) 107 108 ## How to Build and Debug 109 110 1. Build PowerToys Project in debug mode 111 2. Set Hosts as the startup project 112 3. Launch Hosts File Editor in debug mode 113 4. Attach the debugger to PowerToys.Hosts.dll 114 5. Add breakpoints in the Hosts code