Skip to content

Agents.md

Latest commit

 

History

History
123 lines (84 loc) · 4.4 KB

Agents.md

File metadata and controls

123 lines (84 loc) · 4.4 KB

Agents Instructions

Architecture Overview

This is the Power Platform VS Code extension that provides tooling for creating, building, and deploying Power Platform solutions, packages, and portals. It integrates the Power Platform CLI (pac) directly into VS Code.

Key Components

  • Client (src/client/): Main VS Code extension logic, UI components, and Power Pages tooling
  • Server (src/server/): Language servers for HTML/Liquid and YAML files
  • Debugger (src/debugger/): PCF debugging capabilities for Power Platform components
  • Web (src/web/): VS Code for Web support
  • Common (src/common/): Shared utilities, telemetry, and services

Critical Architecture Patterns

  1. PAC CLI Integration: The extension automatically downloads and manages the Power Platform CLI (src/client/lib/CliAcquisition.ts, src/client/pac/PacWrapper.ts)
  2. Multi-Target Build: Uses webpack to build for desktop VS Code, web, and language servers (webpack.config.js)
  3. Telemetry-First: Comprehensive telemetry using OneDSLogger for both desktop and web (src/common/OneDSLoggerTelemetry/)
  4. Service Architecture: Core services in src/common/services/ (ArtemisService, BAPService, PPAPIService)

Development Workflows

Build Commands

  • npm run build or gulp: Full build (uses gulpfile.mjs)
  • npm run compile-web: Build web version only
  • npm run test-desktop-int: Run desktop integration tests
  • npm run test-web-integration: Run web integration tests

Key Files for Extension Development

  • src/client/extension.ts: Main extension entry point
  • package.json: Extension manifest with commands and contributions
  • src/client/lib/PacActivityBarUI.ts: Activity bar panels and UI registration
  • src/client/PortalWebView.ts: Power Pages portal webview management
  • src/client/pac/PacWrapper.ts: Wrapper for Power Platform CLI commands
  • src/client/power-pages/actions-hub/ActionsHubTreeDataProvider.ts: Power Pages Actions Hub tree data provider

PAC CLI Integration Patterns

// Always use PacWrapper for CLI operations
const pacWrapper = new PacWrapper(context);
await pacWrapper.executeCommand(['solution', 'list']);

Coding Guidelines

Indentation & Style

  • Use 4 spaces for indentation (no tabs)
  • Arrow functions => over anonymous functions
  • Curly braces on same line, always use braces for loops/conditionals
  • No whitespace in parenthesized constructs: for (let i = 0; i < 10; i++)

Naming Conventions

  • PascalCase: type names, enum values
  • camelCase: function/method names, property names, local variables
  • UPPER_CASE: constants
  • Use whole words when possible

Strings & Localization

  • "double quotes" for user-facing strings that need localization
  • 'single quotes' for internal strings
  • All user-visible strings MUST be externalized using vscode-nls

Comments

  • Use JSDoc style comments for functions, interfaces, enums, and classes
  • Include parameter descriptions and return types

Workflow

  • Use async/await for asynchronous code
  • When modifying any localization strings, run npm run translations-export to ensure updates are captured.

Testing Patterns

Framework Usage

  • Mocha test framework with describe and it blocks
  • Chai expect assertions (not assert)
  • Sinon for stubs and spies
  • Mock dependencies extensively for unit tests

Test Organization

  • Unit tests: src/*/test/unit/
  • Integration tests: src/*/test/integration/
  • No //Arrange, //Act, //Assert comments

Running Tests

npm run test              # Unit tests
npm run test-desktop-int  # Desktop integration tests
npm run test-web-integration  # Web integration tests

Power Platform Specific Patterns

Power Pages Development

  • Portal files use specific extensions: .copy.html, .custom_javascript.js (see src/common/constants.ts)
  • File system callbacks in src/client/power-pages/fileSystemCallbacks.ts
  • Bootstrap diff functionality for portal template updates

CLI Version Management

  • CLI versions managed in src/client/lib/CliAcquisition.ts
  • Global storage for CLI binaries in VS Code's global storage path
  • Cross-platform support (Windows .exe, Unix executables)

Telemetry Implementation

  • Use oneDSLoggerWrapper for all telemetry events
  • Events defined in src/common/OneDSLoggerTelemetry/telemetryConstants.ts
  • Separate telemetry for desktop vs web experiences