4.2.1. Solutions and Environment Variables
💡 First Principle: A solution is the shipping container for Power Platform work: the agent and everything it depends on — topics, agent flows, custom prompts, connectors, connection references — packaged as one versioned unit that arrives whole or not at all. Environment variables are the container's dials: the values that should differ per environment, externalized so the contents never change.
The working rules:
| Rule | Practice |
|---|---|
| Build in a custom solution | Create it with a publisher and prefix before building; the Default solution can't ship as a managed unit |
| Unmanaged in dev, managed downstream | Unmanaged = editable workbench; managed = sealed deployment artifact for test/prod |
| Dependencies travel together | Add the agent with its flows, prompts, connectors — an agent without its flow is a broken import |
| Externalize per-environment values | Environment variables for URLs, IDs, data source pointers; secret-type variables for credentials (Key Vault-backed) |
| Rebind connections per environment | Connection references let each environment supply its own credentials without touching the components |
Environment variables are the subtle exam favorite. A text variable holds the API URL that differs between test and prod; a data source variable points the same agent at dev-SharePoint in dev and prod-SharePoint in prod; a secret variable references a vault instead of embedding a credential. At deployment, each environment supplies its values — the solution's contents stay byte-identical, which is the whole promise. Bringing an existing agent under ALM is the same discipline retrofitted: add it to a custom solution, then hunt down its hard-coded environment-specific values and replace them with variables before first deployment, not after.
⚠️ Common Misconception: Environment variables are just named constants. They are per-environment configuration slots — the value is supplied by the environment at deploy time, which is precisely what lets one managed solution serve dev, test, and prod unchanged.
Reflection Question: An agent's flow posts to a test webhook URL that must become the prod URL after deployment. Show the wrong fix (and why ALM forbids it) and the right fix (and where the prod value gets entered).
