jcaudillo/Plataforma-de-desarrolladores
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Plataforma-de-desarrolladores/AGENTS.md
Jorge Luis caudillo esparza 6685ef63fb Initial commit
2026-07-14 11:15:57 -07:00

23 KiB
Raw Permalink Blame History

AGENTS.md

Project identity

This project is Plataforma de Desarrolladores Agua Hillo.

It is an ASP.NET WebForms application using C# and .NET Framework 4.8 or 4.8.1.

Do not convert this project to:

  • ASP.NET Core
  • Razor Pages
  • MVC Core
  • Blazor
  • Minimal APIs
  • Angular-only app
  • Web API-only app

ASP.NET WebForms must stay on .NET Framework. If a command, package, or template requires ASP.NET Core, do not use it for this project.

Main goal

Create a clean WebForms starter project from zero, keeping the same Metronic visual style and only the necessary bundle methods used by the master page and login page.

The project must use a contract/service structure so pages, master page, login, menu, user session, and future modules do not connect directly to database classes.

Target architecture:

ASPX / Master Page / User Controls
    ↓
Contracts
    ↓
Services
    ↓
Repositories / SQL helpers
    ↓
Database

Language rules

  • All new code must be C#.
  • Do not add VB.NET files.
  • Do not add .vb files to the active project.
  • Old VB files may exist only as migration reference files using .vb.txt.
  • Do not use VB comment syntax in C# files.
  • Do not use JavaScript/CSS/Powershell comments as C# comments.

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

Project folder rules

Use this base structure:

SIG.Web/
  AppCode/
    Infrastructure/
    Sql/
    Repositories/
    Security/
    Utilities/
    Contracts/
    Models/
    Services/
  Styles/
  Scripts/
  Metronic/
  Site.master
  Site.master.cs
  Login.aspx
  Login.aspx.cs
  Inicio.aspx
  Inicio.aspx.cs
  BundleConfig.cs
  Global.asax
  Global.asax.cs
  Web.config

Rules:

  • Do not place database access directly inside .aspx.cs, .ascx.cs, or Site.master.cs.
  • Database-related helpers go under App_Code/Sql or a clearly named SQL/data folder.
  • Business access goes through Contracts and Services.
  • If the project file needs explicit compilation entries, include C# files recursively, for example App_Code\**\*.cs, but avoid duplicate compile entries that include the same file twice.

Asset folder rules

The following folders are legacy visual dependencies and must be copied as complete folders:

Styles/
Scripts/
Metronic/

Do not replace Metronic with Bootstrap-only layout. Do not upgrade Metronic unless the user explicitly asks. Do not remove old scripts just because they look unused; only remove references from bundles when they are not used by the master/login flow.

Bundle rules

The project must implement only the bundle methods needed by the current Site.master and login page.

Do not bring every old bundle method from the legacy project. Do not add unused bundle groups just because they existed before. Do not add duplicate bundle keys. Do not add empty bundle methods.

Allowed current bundle keys are the ones actually rendered by master/login, especially:

~/bundles/modernizr
~/bundles/scripts
~/bundles/highcharts
~/Metronic/assets/global/scripts/JSV1
~/Metronic/assets/global/css/cssV1

WebForms/AjaxControlToolkit support bundles are allowed only when referenced by ScriptManager or required by WebForms controls:

~/bundles/jquery
~/bundles/WebFormsJs
~/bundles/MsAjaxJs
~/Content/AjaxControlToolkit/Styles/Bundle

Rules:

  • If Site.master or Login.aspx does not render a bundle, do not add it.
  • If a bundle exists only for old pages not migrated yet, leave it out until the page needs it.
  • Prefer preserving original asset paths from Styles, Scripts, and Metronic.
  • Use CssRewriteUrlTransform for CSS bundles that reference fonts, images, or relative URLs.
  • Do not register CSS/JS from server controls when the style/script is global; use BundleConfig and the master page.

WebForms page rules

All normal .aspx pages must use Site.master, except the login page.

Normal pages:

  • Must include MasterPageFile="~/Site.master".
  • Must not include <html>, <head>, <body>, or <form>.
  • Must use <asp:Content> controls.
  • Should inherit from ClsPaginaBase or the current C# page base class.
  • Must not connect directly to SQL classes.
  • Must call contracts/services for data, authentication, permissions, catalogs, menus, and user context.

Public registration exception:

  • Pages/Security/RegistroCliente.aspx, RegistroPendiente.aspx and VerificarCorreo.aspx may be standalone public pages with their own form runat="server".
  • RegistroCliente.aspx keeps its two-step draft in encrypted ViewState and persists only after all client/company validations pass.
  • All persistence continues through contracts/services/repositories and stored procedures.

Login page:

  • Is the only page allowed to have its own full HTML structure.
  • May inherit from System.Web.UI.Page or its own login base class.
  • Must not inherit from ClsPaginaBase if that base class requires an authenticated session.
  • Must use IAuthContract or the current auth contract.
  • Must create a dummy session until real authentication is implemented.
  • Must not hardcode real database login logic in Login.aspx.cs.

Important naming rule:

  • Do not create both Login.aspx and LogIn.aspx.
  • If the starter already uses LogIn.aspx, keep that name and keep Web.config consistent.
  • If creating from scratch, prefer Login.aspx, but update Web.config, redirects, and links consistently.

Master page rules

Site.master owns the main HTML structure.

Rules:

  • Site.master owns the only main <form runat="server">.
  • Site.master must keep the Metronic layout structure.
  • Keep the sidebar/header/page-content structure similar to the original Metronic project.
  • Do not restore the hidden search box from the old header.
  • Keep the actions button if it exists in the selected master layout.
  • Do not hardcode real user/menu database logic inside Site.master.cs.
  • User data must come from a contract/service.
  • Menu data must come from a contract/service.
  • Breadcrumb/title/layout data must come from a contract/service when dynamic.
  • Do not use <title id="Titulo" runat="server">.
  • Prefer <title><%: Page.Title %></title>.
  • If a generated starter currently uses a title literal, replace it with Page.Title unless there is a specific reason to keep the literal.

Current preferred contracts:

IAuthContract
IUserSessionContract
IMenuContract
IMasterPageContract

If old names such as IUserContextProvider or IMenuProvider exist, migrate them to the current contract naming or create adapters. Do not keep two competing naming systems.

ContentPlaceHolder rules

Site.master must use short placeholder IDs.

Preferred final placeholder IDs:

H = page-specific head/CSS content
C = main page content
J = page-specific JavaScript

Example in Site.master:

<asp:ContentPlaceHolder ID="H" runat="server" />
<asp:ContentPlaceHolder ID="C" runat="server" />
<asp:ContentPlaceHolder ID="J" runat="server" />

Example in a normal page:

<asp:Content ID="ContentHead" ContentPlaceHolderID="H" runat="server">
</asp:Content>

<asp:Content ID="ContentMain" ContentPlaceHolderID="C" runat="server">
</asp:Content>

<asp:Content ID="ContentScripts" ContentPlaceHolderID="J" runat="server">
</asp:Content>

If the generated starter currently has HeadContent, MainContent, or ScriptsContent, rename them to H, C, and J before adding more pages.

Do not mix placeholder naming systems in the same project.

Login and session rules

Authentication must go through a contract.

Required flow:

Login.aspx.cs
  ↓
IAuthContract
  ↓
DummyAuthContract now, real AuthService later
  ↓
IUserSessionContract
  ↓
Session user

Initial login may be dummy.

Dummy session user should be safe and clearly fake, for example:

UserId: 15
CompanyId: 1
RoleId: 1
RoleName: Administrador
CompanyName: Empresa Demo
DisplayName: Usuario Demo

Rules:

  • Dummy login may accept any non-empty username and password during starter setup.
  • Mark dummy authentication clearly in code comments.
  • Do not mix real SQL authentication with dummy authentication in the same class.
  • When real login is implemented, create a new service such as SqlAuthContract or AuthService.
  • Do not store passwords in session.
  • Do not log raw passwords.
  • Use Forms Authentication if staying with classic WebForms auth.

Contract rules

Contracts belong in /Contracts.

Current minimum contracts:

Contracts/IAuthContract.cs
Contracts/IUserSessionContract.cs
Contracts/IMenuContract.cs
Contracts/IMasterPageContract.cs

Suggested future contracts:

Contracts/IPermissionContract.cs
Contracts/INotificationContract.cs
Contracts/ICatalogSearchContract.cs
Contracts/IAuditContract.cs
Contracts/ICurrentCompanyContract.cs

Rules:

  • Pages call contracts, not SQL classes.
  • Master page calls contracts, not SQL classes.
  • Login calls contracts, not SQL classes.
  • Contracts must return models, DTOs, or result objects, not raw DataTable unless migrating legacy code.
  • If legacy DataTable is required, isolate it behind a contract and document why.

Service rules

Services belong in /Services.

Current starter services may include:

Services/ContractRegistry.cs
Services/DummyAuthContract.cs
Services/UserSessionContract.cs
Services/DummyMenuContract.cs
Services/MasterPageContract.cs

Rules:

  • ContractRegistry may be used as a simple manual dependency resolver for WebForms.
  • Do not introduce a complex dependency injection framework unless required.
  • Services may depend on SQL helpers/repositories.
  • .aspx.cs files should be thin and delegate work to services.
  • Keep dummy services separate from SQL-backed services.

Model rules

Models belong in /Models.

Current starter models may include:

Models/AppUser.cs
Models/LoginResult.cs
Models/MenuItemModel.cs
Models/MasterLayoutModel.cs
Models/BreadcrumbItem.cs

Rules:

  • Use models to move data between contracts and WebForms pages.
  • Do not pass anonymous objects across layers.
  • Do not expose SQL connection classes or SqlDataReader from services to pages.
  • Keep models simple and serializable when possible.

Database and SQL structure rules

All database connection structure must be centralized under App_Code/Sql or an equivalent SQL/data folder.

Current starter SQL structure:

App_Code/Sql/ConnectionNames.cs
App_Code/Sql/IConnectionStringProvider.cs
App_Code/Sql/WebConfigConnectionStringProvider.cs
App_Code/Sql/SqlConnectionFactory.cs
App_Code/Sql/SqlQueryExecutor.cs

Rules:

  • Define connection names in one place.
  • Read connection strings from Web.config.
  • Do not hardcode connection strings in pages, master, controls, or services.
  • Do not create SqlConnection directly in .aspx.cs.
  • Do not create SqlCommand directly in .aspx.cs.
  • Use repositories or SQL executor classes behind contracts.
  • All application database reads and writes must use stored procedures; inline SQL in C# is prohibited.
  • Mandatory: read and follow AGENTS_STORED_PROCEDURES.md for naming, output parameters, TRY/CATCH, logging, transactions, and logical deletion.
  • Mandatory: read and follow AGENTS_DATA_READER_MAPPING.md for object, list, DataTable, and JArray result mapping.
  • Mandatory: read and follow AGENTS_DATABASE_ERROR_LOGGING.md for safe parameter logging and reproducible stored-procedure calls.
  • Mandatory: read and follow AGENTS_PAGE_STRUCTURE.md for the Pages/Modulo/ location of all new WebForms pages.
  • Mandatory: read and follow AGENTS_WEBFORMS_PARTIAL_POSTBACKS.md for the single master form, ScriptManager ownership, UpdatePanel usage, and partial-postback rules.
  • Mandatory: read and follow AGENTS_JAVASCRIPT_INITIALIZATION.md for per-element initialization flags, global event guards, and idempotent control setup after partial postbacks.
  • Keep stored procedure names centralized.
  • Repositories must use CommandType.StoredProcedure and parameterized inputs/outputs.
  • Never concatenate raw user input into SQL.

Recommended Web.config connection string pattern:

<connectionStrings>
  <add name="DefaultConnection" connectionString="..." providerName="System.Data.SqlClient" />
  <add name="SecurityConnection" connectionString="..." providerName="System.Data.SqlClient" />
  <add name="ReportingConnection" connectionString="..." providerName="System.Data.SqlClient" />
</connectionStrings>

Base page rules

Normal pages should inherit from a C# base page.

Preferred base class:

App_Code/Infrastructure/ClsPaginaBase.cs

If the starter currently has WebFormsPageBase.cs, either:

  • rename it to ClsPaginaBase.cs, or
  • keep WebFormsPageBase and update this AGENTS.md/project rules consistently.

Do not keep both base classes doing the same job.

Base page responsibilities:

  • Validate authenticated session.
  • Expose current user from IUserSessionContract.
  • Provide helper methods for messages, redirects, and permissions.
  • Avoid database access.
  • Avoid page-specific business logic.

Global.asax rules

Global.asax / Global.asax.cs should:

  • Register bundles through BundleConfig.RegisterBundles(BundleTable.Bundles).
  • Configure basic application startup.
  • Avoid business logic.
  • Avoid direct database startup queries unless absolutely required.

If OWIN is not used, prevent startup errors by adding this to Web.config:

<add key="owin:AutomaticAppStartup" value="false" />

Do not add OWIN packages unless the project actually needs OWIN.

Web.config rules

Web.config must stay compatible with ASP.NET WebForms on .NET Framework 4.8/4.8.1.

Rules:

  • Use Forms Authentication unless a different auth system is explicitly requested.
  • Allow anonymous access only to the login page and required static assets.
  • Do not add ASP.NET Core middleware settings.
  • Do not add unsupported .NET Core config sections.
  • Do not add CodeDom provider entries unless the matching NuGet package is installed.
  • If this error appears: No se pudo ubicar el tipo de proveedor CodeDom Microsoft.CodeDom.Providers.DotNetCompilerPlatform..., either install the exact package version or remove/fix the system.codedom section.
  • Keep MIME mappings for fonts such as .woff and .woff2 when Metronic requires them.

OWIN rule

If the application shows this error:

No assembly found containing an OwinStartupAttribute

And the project does not use OWIN, add this in appSettings:

<add key="owin:AutomaticAppStartup" value="false" />

Do not create an empty OWIN startup class just to silence the error unless OWIN is actually required.

Site.master rendering rules

The master page should render bundles and scripts in this general order:

Inside <head>:

<%: Scripts.Render("~/bundles/modernizr") %>
<%: Styles.Render("~/Content/AjaxControlToolkit/Styles/Bundle") %>
<%: Styles.Render("~/Metronic/assets/global/css/cssV1") %>
<asp:ContentPlaceHolder ID="H" runat="server" />

Inside <form> near the top:

<asp:ScriptManager ID="TSM" runat="server" />
<%: Scripts.Render("~/bundles/scripts") %>

Before closing </form>:

<%: Scripts.Render("~/Metronic/assets/global/scripts/JSV1") %>
<%: Scripts.Render("~/bundles/highcharts") %>
<asp:ContentPlaceHolder ID="J" runat="server" />

Rules:

  • Do not render the same script twice.
  • Do not render JQuery twice.
  • Keep ScriptManager if AjaxControlToolkit, UpdatePanel, or WebForms AJAX is used.
  • Keep TSM_AsyncPostBackError only if implemented in code-behind.
  • Remove or implement any event handler referenced by markup.

Header/menu rules

The master header must preserve the selected Metronic layout.

Rules:

  • Keep user dropdown.
  • Keep logout option.
  • Keep actions button when present.
  • Do not restore the hidden/old search box from legacy header.
  • Sidebar menu must be built from IMenuContract.
  • Do not build the menu from SQL inside Site.master.cs.
  • Menu items should use MenuItemModel or an equivalent model.
  • Encode text output when generating HTML menu strings.

Page title and breadcrumb rules

Page title and breadcrumb should be handled consistently.

Rules:

  • Use Page.Title for the browser title.
  • Use a master/layout model for visible page title and breadcrumb.
  • Do not hardcode global breadcrumb logic in every page.
  • Normal pages may set page title in Page_Load or via properties.

Preferred model:

MasterLayoutModel
  PageTitle
  Breadcrumbs
  CurrentUser
  MenuItems

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

  • 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.

JavaScript and CSS rules

  • Global scripts/styles must be registered in BundleConfig and rendered by master.
  • Page-specific scripts go in placeholder J.
  • Page-specific CSS/head content goes in placeholder H.
  • Do not inline large JavaScript blocks in .aspx unless page-specific and small.
  • Do not remove existing custom legacy files unless the user asks.
  • Fix null addEventListener errors by checking that the element exists before attaching events.
  • Avoid blocking Ctrl+V unless a specific feature requires it.

User control rules

If server controls are migrated:

  • Prefer C# classes under App_Code/SigControls when creating reusable server controls.
  • Do not mix WebForms .ascx user controls with App_Code server-control classes unless there is a clear reason.
  • Do not register global CSS/JS from the control when master bundles already include them.
  • Controls should expose properties/events and avoid direct SQL access.
  • Controls should call contracts/services when they need data.

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.

Home page rules

Use only one active home page convention.

Allowed options:

Default.aspx
Inicio.aspx

Rules:

  • Do not keep both as competing entry pages.
  • If using Inicio.aspx, redirect Default.aspx to Inicio.aspx or update Forms Authentication default URL.
  • If using Default.aspx, keep Web.config and menu links pointing to Default.aspx.
  • The home page must use Site.master.

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.

What not to add yet

Do not add the following until the user explicitly asks:

  • Real SQL login implementation
  • Full permission system
  • Notifications
  • Web Push
  • PDF viewer
  • BuscadorCatalogo
  • DropdownGrid
  • PorcentajeBox
  • Angular
  • APIs
  • Background jobs
  • OWIN
  • Entity Framework
  • Dependency injection framework
  • New Metronic version

The starter must stay small and focused: commands, master page, login, contracts, dummy user session, bundle structure, copied assets, and centralized SQL foundation.

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:

  1. Replace dummy login with SQL-backed IAuthContract.
  2. Replace dummy menu with SQL-backed IMenuContract.
  3. Add permission contract.
  4. Add base page authorization checks.
  5. Add reusable controls one by one.
  6. Add catalog search and UI helpers.
  7. 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.