Add csharp-library-rules.md: unified System.Web namespace documentation

csharp-library-rules.md

@@ -0,0 +1,253 @@
+# C# Library Rules: System.Web
+
+## Overview
+
+The `System.Web` namespace provides classes and interfaces that enable browser-server communication in ASP.NET web applications. This document defines rules and guidelines for using the types within the `System.Web` directory.
+
+---
+
+## HttpContext
+
+**Namespace:** `System.Web`
+
+**Description:** Encapsulates all HTTP-specific information about an individual HTTP request.
+
+**Rules:**
+- Always access `HttpContext` through `HttpContext.Current` on the server side.
+- Do not store `HttpContext` instances in static fields; it is not thread-safe across requests.
+- Prefer passing `HttpContext` as a parameter rather than relying on `HttpContext.Current` in library code.
+
+**Example:**
+```csharp
+HttpContext context = HttpContext.Current;
+string userAgent = context.Request.UserAgent;
+```
+
+---
+
+## HttpRequest
+
+**Namespace:** `System.Web`
+
+**Description:** Enables ASP.NET to read the HTTP values sent by a client during a Web request.
+
+**Rules:**
+- Always validate and sanitize all values read from `HttpRequest` before use.
+- Use `Request.QueryString`, `Request.Form`, and `Request.Cookies` with null checks.
+- Do not use `Request.RawUrl` directly in redirects without proper validation to prevent open redirect vulnerabilities.
+
+**Example:**
+```csharp
+string name = HttpContext.Current.Request.QueryString["name"] ?? string.Empty;
+```
+
+---
+
+## HttpResponse
+
+**Namespace:** `System.Web`
+
+**Description:** Encapsulates HTTP response information from an ASP.NET operation.
+
+**Rules:**
+- Always call `Response.End()` or `Response.Flush()` appropriately; avoid calling `Response.End()` inside `try` blocks without handling `ThreadAbortException`.
+- Set `Response.ContentType` explicitly before writing content.
+- Use `Response.Redirect` with `endResponse: false` when redirect is inside a `try/catch` block.
+
+**Example:**
+```csharp
+HttpContext.Current.Response.ContentType = "application/json";
+HttpContext.Current.Response.Write(jsonString);
+HttpContext.Current.Response.End();
+```
+
+---
+
+## HttpServerUtility
+
+**Namespace:** `System.Web`
+
+**Description:** Provides helper methods for processing Web requests.
+
+**Rules:**
+- Use `Server.HtmlEncode` to encode any user-supplied content rendered in HTML output.
+- Use `Server.UrlEncode` for encoding URL parameters.
+- Use `Server.MapPath` only in web application contexts; do not use it in library projects that may run outside of IIS.
+
+**Example:**
+```csharp
+string safeOutput = HttpContext.Current.Server.HtmlEncode(userInput);
+string filePath = HttpContext.Current.Server.MapPath("~/App_Data/config.xml");
+```
+
+---
+
+## HttpApplication
+
+**Namespace:** `System.Web`
+
+**Description:** Defines the methods, properties, and events common to all application objects within an ASP.NET application.
+
+**Rules:**
+- Place application-wide event handlers (`Application_Start`, `Application_End`, etc.) in `Global.asax.cs`.
+- Do not perform long-running synchronous work inside `HttpApplication` event handlers.
+- Register `IHttpModule` implementations in `HttpApplication.Init` rather than using `Global.asax` when reuse across projects is needed.
+
+**Example:**
+```csharp
+protected void Application_Start(object sender, EventArgs e)
+{
+    RouteConfig.RegisterRoutes(RouteTable.Routes);
+}
+```
+
+---
+
+## IHttpHandler
+
+**Namespace:** `System.Web`
+
+**Description:** Defines the contract that ASP.NET implements to synchronously process HTTP Web requests.
+
+**Rules:**
+- Implement `IsReusable` as `false` unless the handler is stateless and thread-safe.
+- Always set an appropriate `Response.ContentType` inside `ProcessRequest`.
+- Register handlers in `web.config` under `<system.web><httpHandlers>` or `<system.webServer><handlers>`.
+
+**Example:**
+```csharp
+public class MyHandler : IHttpHandler
+{
+    public bool IsReusable => false;
+
+    public void ProcessRequest(HttpContext context)
+    {
+        context.Response.ContentType = "text/plain";
+        context.Response.Write("Hello from handler");
+    }
+}
+```
+
+---
+
+## IHttpModule
+
+**Namespace:** `System.Web`
+
+**Description:** Provides module initialization and disposal events to the implementing class.
+
+**Rules:**
+- Always unsubscribe from application events in `Dispose` to prevent memory leaks.
+- Keep module logic lightweight; defer heavy processing to async tasks.
+- Register modules in `web.config` under `<system.web><httpModules>` or `<system.webServer><modules>`.
+
+**Example:**
+```csharp
+public class LoggingModule : IHttpModule
+{
+    public void Init(HttpApplication context)
+    {
+        context.BeginRequest += OnBeginRequest;
+    }
+
+    private void OnBeginRequest(object sender, EventArgs e)
+    {
+        // Logging logic here
+    }
+
+    public void Dispose() { }
+}
+```
+
+---
+
+## HttpCookie
+
+**Namespace:** `System.Web`
+
+**Description:** Provides a type-safe way to create and manipulate individual HTTP cookies.
+
+**Rules:**
+- Always set `HttpOnly = true` on cookies that do not need to be accessed by client-side scripts.
+- Always set `Secure = true` on cookies transmitted over HTTPS.
+- Set an explicit `Expires` value or use session cookies intentionally.
+- Do not store sensitive information (passwords, tokens) in cookies without proper encryption.
+
+**Example:**
+```csharp
+HttpCookie cookie = new HttpCookie("sessionId", sessionToken)
+{
+    HttpOnly = true,
+    Secure = true,
+    Expires = DateTime.UtcNow.AddHours(1)
+};
+HttpContext.Current.Response.Cookies.Add(cookie);
+```
+
+---
+
+## HttpSessionState
+
+**Namespace:** `System.Web.SessionState`
+
+**Description:** Provides access to session-state values as well as session-level settings and lifetime management.
+
+**Rules:**
+- Avoid storing large objects in session state to minimize memory consumption.
+- Always check for `null` before accessing session values.
+- Use typed helper methods or wrapper classes instead of casting session objects directly.
+- Prefer distributed session providers (e.g., SQL Server, Redis) over in-process sessions in web farm scenarios.
+
+**Example:**
+```csharp
+Session["userId"] = user.Id;
+int userId = (Session["userId"] as int?) ?? 0;
+```
+
+---
+
+## HttpRuntime
+
+**Namespace:** `System.Web`
+
+**Description:** Provides a set of ASP.NET run-time services for the current application.
+
+**Rules:**
+- Use `HttpRuntime.Cache` only for application-level caching; prefer `MemoryCache` in new code.
+- Do not rely on `HttpRuntime.AppDomainAppPath` in portable library code.
+- Use `HttpRuntime.UsingIntegratedPipeline` to branch behavior between Classic and Integrated IIS pipeline modes.
+
+**Example:**
+```csharp
+string appPath = HttpRuntime.AppDomainAppPath;
+```
+
+---
+
+## HttpUtility
+
+**Namespace:** `System.Web`
+
+**Description:** Provides methods for encoding and decoding URLs when processing Web requests.
+
+**Rules:**
+- Use `HttpUtility.HtmlEncode` / `HtmlDecode` for HTML contexts.
+- Use `HttpUtility.UrlEncode` / `UrlDecode` for URL query string values.
+- Prefer `Uri.EscapeDataString` over `HttpUtility.UrlEncode` for encoding individual URI components in non-ASP.NET code.
+- Do not use `HttpUtility` in libraries targeting non-web (.NET Standard) projects without adding the correct NuGet reference.
+
+**Example:**
+```csharp
+string encoded = HttpUtility.HtmlEncode("<script>alert('xss')</script>");
+string decoded = HttpUtility.UrlDecode("hello%20world");
+```
+
+---
+
+## General Rules
+
+- **Do not use `System.Web` in new .NET 5+ projects.** Use `Microsoft.AspNetCore.*` equivalents instead.
+- **Reference assembly:** Add `System.Web` via NuGet (`System.Web` package) only when targeting .NET Framework; it is not available for .NET Core / .NET 5+.
+- **Exception handling:** Catch `HttpException` for HTTP-specific errors and use its `GetHttpCode()` method to retrieve the HTTP status code.
+- **Security:** Never trust user input from any `HttpRequest` property without validation or encoding.
+- **Encoding:** Always encode output using the appropriate `HttpUtility` or `Server` method to prevent XSS vulnerabilities.