AGENTS_MANTENIMIENTO_PROYECTO.md

These rules complement AGENTS.md and are mandatory whenever the task involves commands, security, error handling, user feedback, grids, PDF migration, file delivery, verification, or project evolution.

Command rules

When giving commands for this project:

Prefer PowerShell, Developer PowerShell, or Visual Studio Package Manager Console commands.
Commands must be written in one line.
Do not use PowerShell line continuation with backticks.
Do not suggest dotnet new webforms because WebForms is not supported by the .NET CLI as an ASP.NET Core project.
If a WebForms project must be created from command line, use Visual Studio/MSBuild-compatible project files or create the project through Visual Studio using ASP.NET Web Application (.NET Framework).
Target framework must be .NET Framework 4.8 or .NET Framework 4.8.1.

Recommended project creation path:

mkdir "C:\Proyectos\Agua de hermosillo\Plataforma de Desarrolladores"

cd "C:\Proyectos\Agua de hermosillo\Plataforma de Desarrolladores"

Then create/open the WebForms project in Visual Studio 2022 as:

ASP.NET Web Application (.NET Framework) → Web Forms → C# → .NET Framework 4.8/4.8.1

Security rules

Do not store passwords in code, comments, Web.config examples, or session.
Do not expose real connection strings in committed files.
Use dummy values in examples.
Use parameterized SQL.
Validate uploaded files by extension, MIME type, and size when uploads are later added.
Avoid writing raw exception details to the user in production.
Keep customErrors mode="Off" only for local development.

Error handling rules

Controlled outcomes and technical failures must use different logs.

@ErrorTipo = 1, SQL exceptions, timeouts, contract failures, and unexpected exceptions go to the main technical log.
@ErrorTipo = 2 is a controlled warning. It must not be written to the main technical log.
Controlled warnings go to daily compact files under ~/log/controlled.
Controlled log files retain only the current day and the previous two days. The retention is configured with ControlledLogRetentionDays = 3.
Explicit controlled throws must use ControlledApplicationException; do not classify arbitrary Exception or InvalidOperationException instances as controlled.
Controlled logs record date, source, procedure, URL, and friendly message, but omit full stack traces and replay SQL to remain compact.
A controlled exception must still return a friendly result to the page and must never be presented as an unexpected application failure.
Handle null session user cleanly and redirect to login.
Handle failed login with a friendly message.
Handle async postback errors through ScriptManager.AsyncPostBackError only if the handler exists.
Avoid infinite loading states in JavaScript controls.
For AJAX/server search controls, use client and server timeouts.
Recommended default search timeout: about 20 to 30 seconds unless the user asks otherwise.

Action availability and feedback rules

Do not disable a button or primary action only because a business prerequisite is missing, such as an unassigned client or an empty related catalog.
Keep the action available by default; when the user clicks it, validate the prerequisite and show a clear message explaining why the operation cannot continue and what must be done next.
Never leave a disabled action without an immediately visible explanation.
Before adding Enabled="false", the HTML disabled attribute, or an equivalent disabled CSS/JavaScript state to a catalog or page action, ask the user whether disabling is acceptable or whether a message, modal, link, or other alternative should be used.
A transient disabled state used only while a request is being processed to prevent duplicate submissions is allowed, but the action must be restored when processing finishes.

Grid display rules

Every new or modified asp:GridView must declare GridLines="None".
Its CssClass must include the exact utility class Widthall so the grid uses the full available width.
Do not add table-bordered to a GridView. Existing visual classes such as table, table-striped, and table-hover may be retained when appropriate.
Keep GridView declarations and their columns expanded and indented according to the source code readability rules.
Detail-page navigation from a GridView or list must use asp:HyperLink or another real link with NavigateUrl; do not use LinkButton, RowCommand, or a postback only to open a detail page.
URL-building variables and helpers must describe the row entity, for example cveFraccionamiento, fraccionamientoDetalleUrl, or GetFraccionamientoDetalleUrl. Avoid generic names such as id, itemUrl, or detailUrl when the entity is known.

PDF viewer migration rules

If the PDF viewer is added to this project later:

Implement it in C#.
Prefer App_Code/SigControls for server controls.
Do not add VB files.
Do not use /* */ comments in VB reference files; VB references must remain .vb.txt only.
Keep global PDF viewer CSS/JS references in bundles.
Do not register duplicate resources from the control and master at the same time.
Session or temp-folder PDF storage must be explicit and centralized.

File delivery rules for this project

When generating a single downloadable file:

If the file is .js or .css and it is not inside a ZIP, append .txt to the filename.
Example: custom.js.txt, styles.css.txt.
If the file is inside a ZIP, keep the real extension .js or .css.
For project-level delivery, prefer ZIP files.

Current implementation checklist

When modifying or regenerating the project, verify:

Project targets .NET Framework 4.8 or 4.8.1.
All new code is C#.
No active .vb files were added.
Styles, Scripts, and Metronic were copied as-is.
BundleConfig.cs contains only bundles rendered by master/login or required by WebForms AJAX.
Site.master owns the only main form.
Normal pages use Site.master.
Normal pages do not contain full HTML structure.
Login is the only standalone full HTML page.
User/session data comes from IUserSessionContract.
Login uses IAuthContract.
Menu comes from IMenuContract.
Master layout data comes from IMasterPageContract.
SQL connection helpers are centralized under App_Code/Sql.
Pages do not directly instantiate SQL connections.
Placeholder IDs are H, C, and J.
No hidden old search box was restored.
Actions button is preserved when present in the selected layout.
Web.config login URL matches the actual login page filename.
No duplicate Login.aspx / LogIn.aspx pages exist.
No OWIN startup error exists, or OWIN automatic startup is disabled.
No missing CodeDom provider error exists.

Preferred next evolution

After the starter works, the safest growth path is:

Replace dummy login with SQL-backed IAuthContract.
Replace dummy menu with SQL-backed IMenuContract.
Add permission contract.
Add base page authorization checks.
Add reusable controls one by one.
Add catalog search and UI helpers.
Add PDF viewer only after the base shell is stable.

Keep every new feature behind contracts so the WebForms UI remains thin and easier to migrate later if needed.

7.4 KiB Raw Blame History