Ppds Plugins

PPDS Plugins — registration as code, traces as evidence

PPDS replaces Plugin Registration Tool clicks with attributes on the plugin class. Registration metadata is extracted from the compiled assembly, reviewed as JSON, diffed against the environment, and deployed deterministically. Attribute reference (all properties, verified): [references/plugin-attributes.md](references/plugin-attributes.md). Exact CLI flags: [references/cli-plugins.md](references/cli-plugins.md).

Surface routing: deployment is CLI-only. For read-side analysis from an MCP-only host: ppds_plugins_list, ppds_plugins_get, ppds_plugin_traces_list, ppds_plugin_traces_get, ppds_plugin_traces_timeline, ppds_plugin_traces_delete.

The declarative loop

# 0. Code: decorate plugin classes with [PluginStep] / [PluginImage] / [CustomApi]
#    (PPDS.Plugins NuGet package, net462) and build.

# 1. Extract attribute metadata from the assembly to JSON
ppds plugins extract --input bin/Release/net462/MyPlugins.dll --output registrations.json

# 2. Diff against what the environment actually has
ppds plugins diff --config registrations.json

# 3. Preview the deployment (always before the real run — safety model rule 3)
ppds plugins deploy --config registrations.json --dry-run

# 4. Deploy (after the user has seen the preview)
ppds plugins deploy --config registrations.json

# 5. Verify
ppds plugins list --assembly MyPlugins

Key facts:

• deploy takes --config registrations.json (required) — it does not

take an assembly path. extract is the step that reads the DLL.

• deploy --clean also removes registrations in the environment that are

missing from the config (orphans). Run --dry-run with --clean first — it deletes.

• --solution on extract/deploy adds components to a solution.
• Step-level management: ppds plugins enable / ppds plugins disable /

ppds plugins unregister, ppds plugins update (swap assembly bytes), ppds plugins download, ppds plugins clean (orphan removal), ppds plugins get.

• Custom APIs declared via [CustomApi] deploy in the same loop; manual

management exists under ppds custom-apis ([references/cli-custom-apis.md](references/cli-custom-apis.md)) and ppds service-endpoints ([references/cli-service-endpoints.md](references/cli-service-endpoints.md)).

Trace debugging recipe

Plugin trace logs are the evidence. Filters: [references/cli-plugintraces.md](references/cli-plugintraces.md).

# 1. Make sure tracing is on (all = verbose; exception = errors only)
ppds plugintraces settings get
ppds plugintraces settings set all

# 2. Reproduce the failing operation (e.g. the Update that misbehaves)

# 3. Find the trace
ppds plugintraces list --errors-only --last-hour --entity account
ppds plugintraces list --type AccountUpdatePlugin --message Update -n 20

# 4. Read it — message block + exception detail
ppds plugintraces get 

# 5. See the whole transaction as a tree (correlation ID — finds chained/
#    nested plugin executions and the slow step)
ppds plugintraces timeline 
ppds plugintraces related           # flat list, same correlation

# 6. Restore trace settings when done (all is noisy and costs storage)
ppds plugintraces settings set exception

# Housekeeping (destructive — preview first; durations like 7d, 24h, 30m)
ppds plugintraces delete --older-than 7d --dry-run

Useful list filters: --mode sync|async, --min-duration (find slow steps), --since/--until (ISO 8601), --correlation-id, --step-id, --record account/, --recursive (nested depth >1 only).

Common mistakes (do not invent these)

| Wrong | Correct | |-------|---------| | ppds plugins deploy --assembly My.dll | extract --input My.dll first, then deploy --config registrations.json | | ppds plugins deploy --file registrations.json | the flag is --config (alias -c) | | ppds plugins register --assembly ... for updates | register is first-time direct registration; the maintained loop is extract → diff → deploy | | ppds plugintraces list --query "..." / --filter-xml | --filter , or the typed flags (--entity, --message, --errors-only, ...) | | ppds traces ... / ppds plugin-traces ... | the group is ppds plugintraces | | Leaving trace level at all | ppds plugintraces settings set exception after debugging |

Skill boundaries

| Need | Use instead | |------|-------------| | Query the data a plugin wrote (verify behavior) | ppds-query | | Add the plugin's solution to ALM flow, import/export | ppds-solutions-alm | | Entity/attribute metadata the plugin depends on | ppds-metadata | | Auth, environment selection, error-code meanings | ppds-core |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: joshsmithxrm
• Source: joshsmithxrm/ppds-skills
• License: MIT

Install and usage instructions live in the source repository linked above.