Add a note about generic host default behaviour when using launchd with default cwd

[rosebyte]

Please see dotnet/runtime#121256

There isn't much we can do in terms of code changes as any change would break a lot of users, however, we can help users understand the situation when they run a generic host based app using launchd without setting the WorkingDirectory in the plist, so they won't have to debug on their own as this situation is difficult to work out in general.

I propose to add these two columns to the very end of the file settings configuration section (https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-9.0#app-settings-file-configuration-appsettingsjson-appsettingsenvironmentjson)

Service managers such as SCM, launchd, or systemd may, if not configured correctly, set the application’s working directory to a location outside the directory that contains the configuration files, commonly the root directory on Unix systems or a drive root such as C:/ on Windows. In this case, the file system watcher may end up monitoring a large portion of the filesystem.

This can lead to unintended side effects, including permission errors when accessing files outside the application directory and unnecessary performance overhead due to the number of files being observed. To avoid these issues, it is recommended to configure the hosting environment or service manager to set an appropriate working directory for the application.

[wadepickett]

@tdykstra, this is for a doc that may be in your area.

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution or answer to your question—it's an internal triage tool that identifies potentially relevant docs, code samples, and versions to look into. A team member will review this issue and respond. Thank you for your contribution!

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-03-01
Issue: 36798
Model: GitHub Copilot

---

Issue Analysis: Add a note about service manager working directory behavior affecting file system watcher in configuration

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

When a .NET application using the Generic Host (Host.CreateDefaultBuilder() or WebApplication.CreateBuilder()) is launched by a service manager (such as macOS launchd, Linux systemd, or Windows SCM) without explicitly configuring the working directory, the application's current directory may default to the system root (/ on Unix, C:\ on Windows). Because the default configuration enables reloadOnChange: true for appsettings.json and appsettings.{ENVIRONMENT}.json, a FileSystemWatcher is created on the content root directory. When that directory is the system root, the watcher monitors the entire file system, causing:

1. Performance overhead from attempting to detect and respond to every file change on the system.
2. Permission errors and alarming system dialogs (especially on macOS) when the watcher's existence checks access files in other applications' sandboxes.

The linked runtime issue (dotnet/runtime#121256) was closed as "not planned" because changing the default behavior would be a breaking change. The issue author proposes a documentation note to help users understand and avoid this problem.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/fundamentals/configuration/index.md	549-563	"App settings file configuration" (end of section)

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential documentation Updates

File: aspnetcore/fundamentals/configuration/index.md
Location: After line 563 (after the paragraph "For other IDEs, check the IDE's documentation..." which is the last paragraph in the "App settings file configuration" section, before the "## Environment Variables Configuration Provider" heading at line 565)
Type: New [!NOTE] block

Current content (lines 561-563):

The preceding setting indicates to VS Code that app settings files, including environmental-based files, are associated with the [JSONC ("JSON with Comments") file format](https://jsonc.org/), which supports comments.

For other IDEs, check the IDE's documentation and product support channels to determine how to silence errors or warnings about comments in JSON files.

Suggested direction:

Add a [!NOTE] block after line 563 with content along the following lines:

> [!NOTE]
> Service managers such as SCM, `launchd`, or `systemd` may, if not configured correctly, set the application's working directory to a location outside the directory that contains the configuration files, commonly the root directory on Unix systems or a drive root such as `C:\` on Windows. Because the default configuration enables `reloadOnChange` for app settings files (see the [preceding paragraph](#app-settings-file-configuration-appsettingsjson-appsettingsenvironmentjson)), a file system watcher is created on the content root directory. When the content root is the system root, the watcher monitors a large portion of the file system.
>
> This can lead to unintended side effects, including permission errors when accessing files outside the application directory and unnecessary performance overhead due to the number of files being observed. To avoid these issues, configure the hosting environment or service manager to set an appropriate working directory for the application. Alternatively, explicitly set the content root using <xref:Microsoft.Extensions.Hosting.HostingHostBuilderExtensions.UseContentRoot%2A> or set `hostBuilder:reloadConfigOnChange` to `false` if configuration file reloading is not needed.

🎯 Suggested Action Plan

For documentation team review

1. Review file: aspnetcore/fundamentals/configuration/index.md

   • Navigate to: Line 563
   • Section: "App settings file configuration (appsettings.json, appsettings.{ENVIRONMENT}.json)"
   • Consider: [!NOTE] block explaining the service manager working directory behavior and its impact on the FileSystemWatcher used for reloadOnChange

2. Consider workarounds to include:

   • Configuring the service manager (launchd plist WorkingDirectory, systemd unit WorkingDirectory=, etc.) to set the working directory to the app's directory
   • Using UseContentRoot() to explicitly set the content root
   • Setting hostBuilder:reloadConfigOnChange=false to disable configuration reload entirely

⚠️ Review Considerations

• This applies to all supported .NET versions (the behavior exists since Host.CreateDefaultBuilder() was introduced)
• The issue is cross-platform (macOS launchd, Linux systemd, Windows SCM) — the note should not be platform-specific
• The linked runtime issue (dotnet/runtime#121256) was closed as "not planned," reinforcing that documentation is the appropriate mitigation
• Consider whether the Generic Host documentation also needs a similar note
• Consider cross-referencing the Disable app configuration reload on change documentation

🔗 References

• Published article: Configuration in ASP.NET Core — App settings file configuration
• Related runtime issue: dotnet/runtime#121256 — On macOS, an application that calls CreateDefaultBuilder() starts a FileSystemWatcher on the system root directory
• Generic Host — Disable reload on change: Disable app configuration reload on change

[wadepickett]

@tdykstra, assigned to you since it is your area. I ran the report above in case that is helpful.

[rosebyte]

@wadepickett, thank you for driving it.
Copilot has a good point with the note, we may take it as an alternative proposal.