Document that HttpListener isn't recommended for new development - #12937
Merged
Conversation
Co-authored-by: MihaZupan <25307628+MihaZupan@users.noreply.github.com>
… types Co-authored-by: MihaZupan <25307628+MihaZupan@users.noreply.github.com>
Copilot created this pull request from a session on behalf of
MihaZupan
August 5, 2026 14:13
View session
Co-authored-by: MihaZupan <25307628+MihaZupan@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the .NET API reference docs to clearly indicate that System.Net.HttpListener is not recommended for new development, and to surface that guidance consistently on related HttpListener* pages via a shared include.
Changes:
- Added a reusable include (
includes/httplistener-not-recommended.md) describing limited servicing and cross-platform behavioral differences, and pointing to ASP.NET Core/Kestrel as the recommended alternative. - Updated
HttpListenertype and constructor docs to reference the “not recommended for new development” guidance and link readers to Remarks. - Added the same guidance to Remarks for commonly visited related types (
HttpListenerContext,Request,Response,PrefixCollection,TimeoutManager).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| includes/httplistener-not-recommended.md | New reusable admonition include explaining why HttpListener isn’t recommended for new development. |
| xml/System.Net/HttpListener.xml | Adds “not recommended” messaging in the type summary and ctor summary and includes the new admonition in Remarks. |
| xml/System.Net/HttpListenerContext.xml | Includes the new admonition in Remarks so guidance appears on the context page directly. |
| xml/System.Net/HttpListenerPrefixCollection.xml | Includes the new admonition in Remarks to surface guidance on the prefixes collection page. |
| xml/System.Net/HttpListenerRequest.xml | Includes the new admonition in Remarks to surface guidance on the request page. |
| xml/System.Net/HttpListenerResponse.xml | Includes the new admonition in Remarks to surface guidance on the response page. |
| xml/System.Net/HttpListenerTimeoutManager.xml | Includes the new admonition in Remarks to surface guidance on the timeout manager page. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
rzikm
approved these changes
Aug 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
HttpListeneris effectively in maintenance mode and its behavior differs substantially across platforms, but the docs gave no signal that it shouldn't be used for new code. This adds guidance following the existing pattern used forHttpWebRequestandSmtpClient.Changes
includes/httplistener-not-recommended.mdcarries an[!IMPORTANT]notice stating thatHttpListenerreceives only limited servicing, that its implementation and protocol support vary by platform (WindowsHTTP.sysvs. a managed implementation on Linux/macOS with no HTTPS support), and pointing to ASP.NET Core/Kestrel as the recommended alternative.HttpListener— include referenced from the type remarks and the constructor remarks; both summaries now end with "not recommended for new development; for more information, see the Remarks section," matchingSmtpClient.HttpListenerContext,HttpListenerRequest,HttpListenerResponse,HttpListenerPrefixCollection, andHttpListenerTimeoutManager, since users frequently land on those pages directly rather than on theHttpListenerpage.Notes for reviewers
HttpListenerException,HttpListenerBasicIdentity, andHttpListener+ExtendedProtectionSelectorwere left untouched — they're narrow helper/exception types and unlikely entry points. Happy to add the notice there if preferred.HttpListener.Start) don't inherit type remarks.HttpWebRequestrepeats its notice on every member; that was not done here to avoid excessive noise, but it's an option if consistency is preferred.Internal previews