Skip to content

AGENTS.md

Latest commit

 

History

History
100 lines (73 loc) · 3.49 KB

AGENTS.md

File metadata and controls

100 lines (73 loc) · 3.49 KB
Raw

Agent Instructions for Profile Explorer

Git Policy

NEVER commit or git add without explicit user permission. When asked for a commit message, provide the message text only - do not execute git commit or git add.

Building

IMPORTANT: Always use Release configuration (-c Release). The user runs Release builds, not Debug.

Before Building

Always check if ProfileExplorer is running before attempting a build - it locks the DLLs:

tasklist /FI "IMAGENAME eq ProfileExplorer.exe" 2>nul | find /i "ProfileExplorer"

If running, ask the user to close it before building.

Build Commands

# Full UI build (Release)
dotnet build "C:/src/profile-explorer/src/ProfileExplorerUI/ProfileExplorerUI.csproj" -c Release

# Core library only (faster, for checking compilation)
dotnet build "C:/src/profile-explorer/src/ProfileExplorerCore/ProfileExplorerCore.csproj" -c Release

Iterative Development

For faster iteration when ProfileExplorer is running:

  1. Build just the Core project first to check for compilation errors
  2. Ask user to close ProfileExplorer
  3. Build the full UI project
  4. User can relaunch and test

The Core project build is much faster (~2-3s) and doesn't require ProfileExplorer to be closed.

Bumping the App Version

The app version lives in 3 files that must stay in lockstep (history shows they've drifted apart and needed follow-up commits). Use the bump script — never edit these by hand:

# Print current version across all files
.\scripts\Bump-Version.ps1 -Show

# Bump components (1.2.1 -> 1.2.2 / 1.3.0 / 2.0.0)
.\scripts\Bump-Version.ps1 -Bump Patch
.\scripts\Bump-Version.ps1 -Bump Minor
.\scripts\Bump-Version.ps1 -Bump Major

# Set an explicit version
.\scripts\Bump-Version.ps1 -Version 1.5.0

# Preview without writing
.\scripts\Bump-Version.ps1 -Bump Patch -WhatIf

The script refuses to bump when the files disagree on the current version; pass -Version X.Y.Z -Force to force a known-good value. See the script's header comment for full help.

The files it updates:

  • src/ProfileExplorerUI/ProfileExplorerUI.csproj (AssemblyVersion, FileVersion, Version)
  • installer/x64/prepare-installer.cmd
  • installer/arm64/prepare-installer.cmd

Diagnostic Logging

Enable diagnostic logging with:

$env:PROFILE_EXPLORER_DEBUG = "1"

Logs are written to %TEMP%\ProfileExplorer_Diagnostic_*.log

Analyzing Logs

Use the analysis script (don't read raw logs - they're ~12MB):

C:\src\profile-explorer\scripts\Analyze-DiagnosticLog.ps1 -LogPath <path-to-log>

Or grep for specific patterns:

grep -i "pattern" <log-file> | head -30

Key Files

Symbol Loading Performance

  • ETWProfileDataProvider.cs - Main symbol loading orchestration (~lines 759-1150)
  • SymbolFileSourceSettings.cs - Symbol settings including timeouts, filters, caching
  • PEBinaryInfoProvider.cs - Binary file downloading
  • PDBDebugInfoProvider.cs - PDB file downloading

Important Settings (SymbolFileSourceSettings)

  • SymbolServerTimeoutSeconds - Normal timeout (default: 10s)
  • BellwetherTestEnabled - Test symbol server health before bulk downloads
  • BellwetherTimeoutSeconds - Timeout for bellwether test (default: 5s)
  • DegradedTimeoutSeconds - Reduced timeout when server is slow (default: 3s)
  • RejectPreviouslyFailedFiles - Negative caching for failed downloads
  • WindowsPathFilterEnabled - Skip non-Windows binaries
  • CompanyFilterEnabled - Only load symbols for specific companies (e.g., Microsoft)