2.1 Package Deployment & Servicing

2.1 Package Deployment & Servicing

Quick Answer: A Software Deployable Package (SDP) is the standardized, standalone archive (.zip) used to apply code updates, independent software vendor (ISV) solutions, and platform hotfixes to Microsoft Dynamics 365 Finance and Operations environments. In multi-box environments (Tier 2 and Production), packages must be deployed through Microsoft Dynamics Lifecycle Services (LCS) by uploading the package to the Asset Library, validating it in a Tier 2+ Sandbox (UAT) environment, marking it as a Release Candidate, and applying updates through the Maintain menu. In single-box development or build environments (Tier 1), developers apply packages from the command line using AXUpdateInstaller.exe through a four-phase runbook workflow: generate, import, execute, and if necessary, -rerunstep to resume after error remediation.

---

1. Software Deployable Package (SDP) Architecture & Anatomy

In Dynamics 365 Finance and Operations, source code files (X++ classes, XML metadata, table definitions) are never deployed directly into production or user acceptance testing runtimes. Instead, application lifecycle management (ALM) relies on pre-compiled, atomic artifacts known as Software Deployable Packages (SDPs).

Compilation vs. Runtime Deployment

The foundational architectural principle of modern F&O ALM is the strict decoupling of compilation from execution. In legacy AX 2012 systems, code could be compiled directly inside transactional environments using MorphX or the AX client. In modern Dynamics 365 Finance and Operations SaaS architectures, runtime environments do not possess compilers or developer SDKs. All custom source code, table extensions, and metadata structures must be compiled into Common Intermediate Language (.NET CIL) assemblies and packaged alongside database synchronization scripts prior to deployment.

Package Generation Sources

An SDP is produced in one of two ways:

1. Azure DevOps CI/CD Build Pipelines (Recommended Best Practice): An automated build agent compiles all custom source code modules, checks for compile-time errors, executes automated SysTest unit tests, and packages the resulting binaries into an SDP zip artifact using the dedicated build task.
2. Visual Studio Development Environment: A developer manually creates a deployable package from the Visual Studio menu bar by selecting Extensions > Dynamics 365 > Deploy > Create Deployment Package, selecting the target models, and specifying an output directory. While useful for rapid dev-to-dev testing, manual packages are prohibited in enterprise production release gates.

Internal Anatomy of an SDP Archive

An SDP is a standardized .zip archive containing a specific folder hierarchy and manifest files that the deployment engine consumes:

SoftwareDeployablePackage.zip
│
├── HotfixInstallationInfo.xml      <-- Top-level manifest (metadata, dependencies, version)
├── DefaultTopologyData.xml         <-- Maps deployment roles to target machine topology
├── DefaultServiceModelData.xml     <-- Enumerates service models and deployed components
├── AXUpdateInstaller.exe           <-- Command-line runbook orchestrator executable
│
├── AOSService/                     <-- Core Application Object Server deployment payload
│   ├── Scripts/                    <-- PowerShell orchestration scripts (AutoUpdate.ps1, etc.)
│   │   ├── AutoUpdate.ps1          <-- Main component entry point script
│   │   ├── PreDeploy.ps1           <-- Pre-deployment validation and environment prep
│   │   ├── AutoDatabaseSync.ps1    <-- Triggers data dictionary and table synchronization
│   │   └── PostDeploy.ps1          <-- Post-deployment cache flushes and service starts
│   ├── bin/                        <-- Compiled .NET assemblies (.dll) and X++ module assemblies
│   └── package.config              <-- Package dependency and version declarations
│
├── ALMExtension/                   <-- Lifecycle tools and database upgrade scripts
├── BIService/                      <-- Power BI and reporting service integration assets
└── MROSUndoScripts/                <-- Rollback and undo instructions for reporting services

Key Manifest Files and Scripts

• HotfixInstallationInfo.xml: The primary manifest read by LCS and AXUpdateInstaller. It specifies the unique package GUID, display name, release type (Application, Platform, Quality Update), target build version, and any prerequisite packages required.
• DefaultTopologyData.xml: Defines the service machine roles (such as AOS, BI, Management Reporter) and determines which script components apply to which nodes.
• DefaultServiceModelData.xml: Lists all metadata packages, runtime modules, and binary dependencies delivered by the package.
• AutoUpdate.ps1: The central PowerShell driver script executed by the runbook engine on each node. It coordinates service shutdowns, payload extraction, file substitution, and post-installation initialization.
• AutoDatabaseSync.ps1: Executes the full database synchronization utility. It compares compiled data dictionary metadata against the underlying SQL schema, generating necessary ALTER TABLE and CREATE INDEX operations.

Package Typologies: Single Consolidated Package vs. Multiple Packages

In complex enterprise solutions, organizations frequently incorporate multiple custom models alongside third-party Independent Software Vendor (ISV) solutions. Microsoft best practices strictly mandate creating and deploying a single, consolidated deployable package combining all custom models and ISV solutions into one unified artifact.

• Risk of Multiple Packages: Deploying separate packages sequentially triggers repeated downtime windows, causes intermediate state schema mismatches, and risks breaking cross-model dependencies.
• Consolidated Build Pipeline: The Azure DevOps build pipeline should reference both internal source control repositories and ISV binary packages, synthesizing a single master SDP that is tested and promoted as an atomic unit.

---

2. Lifecycle Services (LCS) Package Deployment Workflow

Microsoft strictly enforces that all Tier 2+ sandbox and production environments are serviced exclusively through Lifecycle Services (LCS). Direct administrative RDP access to multi-box Azure SQL databases and AOS virtual machines is disabled in self-service environments, making LCS the sole deployment conduit.

End-to-End LCS Governance Workflow

Pre-Deployment Preparation & Operational Best Practices

Before initiating any package deployment in LCS, administrators must complete three non-negotiable preparation steps:

1. Drain Batch Servers: Any long-running batch jobs (such as inventory closing, Master Planning / MRP, or financial consolidation) must be placed in a Withhold state. Allowing active jobs to run during AOS shutdown risks data corruption, long transaction rollbacks, and incomplete database sync.
2. Verify User Activity: Broadcast a system notification to all active users requesting logoff. LCS automatically terminates remaining active web sessions when initiating servicing, but proactive notification prevents lost transactional work.
3. Confirm Database Backup: In self-service environments, LCS automatically creates a restore point snapshot prior to package deployment. Verify that the target environment has a valid Azure SQL Point-in-Time Restore (PITR) window available.

Rollback Considerations & The Abort Mechanism

If an unexpected failure occurs during an LCS self-service deployment, LCS pauses servicing and provides two administrative actions:

• Resume: Once the administrator addresses an environmental conflict (e.g., clearing a transient network blip or deadlock), selecting Resume retries the failed step.
• Abort: If the package contains a critical defect or cannot be remediated during the change window, clicking Abort instructs LCS to rollback the environment to its pre-servicing binary state.

[!WARNING] Destructive Schema Rollback Trap: The LCS Abort action rolls back system binaries and service configurations, but it does not reverse destructive database schema transformations (e.g., dropped fields or table alterations) executed during the AutoDatabaseSync phase. If destructive schema changes took place, a full Point-in-Time Restore (PITR) of the database is required to return to the exact pre-deployment state.

---

3. Command-Line Servicing with AXUpdateInstaller.exe

On Tier 1 development environments, build virtual machines, and downloaded local VHDs, LCS automated self-service deployment is unavailable. Developers and system engineers deploy software packages manually using the command-line orchestrator: AXUpdateInstaller.exe.

The Four-Phase Command Lifecycle

Servicing via AXUpdateInstaller.exe follows an exact four-command sequential lifecycle. Attempting to skip steps or run them out of order results in runtime termination.

Phase 1: Verify Package Contents (list)

Extract the SDP zip file to an unzipped local directory (for example, C:\DeployablePackages\Package1). Open an administrative PowerShell prompt, navigate to the extracted folder, and view the components:

cd C:\DeployablePackages\Package1
.\AXUpdateInstaller.exe list

This command queries DefaultServiceModelData.xml and prints all service components and metadata models contained within the package.

Phase 2: Generate the Runbook (generate)

The runbook is an XML document that maps each component script to the local environment's topology. Execute the generate command with the required parameters:

.\AXUpdateInstaller.exe generate `
    -runbookid="Sprint42Deploy" `
    -topologyfile="DefaultTopologyData.xml" `
    -servicefileslist="DefaultServiceModelData.xml" `
    -runbooktosetup="Sprint42Deploy-runbook.xml"

• -runbookid: A unique, user-defined identifier for this servicing session.
• -topologyfile: Points to the topology definition included in the package.
• -servicefileslist: Points to the service model manifest.
• -runbooktosetup: The name and path of the target runbook XML file to create.

Phase 3: Register the Runbook (import)

Before the runbook can be executed, it must be registered into the installer's local tracking database:

.\AXUpdateInstaller.exe import -runbookfile="Sprint42Deploy-runbook.xml"

This command validates the XML schema and creates the step-tracking records in the local system registry and temporary working directory.

Phase 4: Execute Deployment (execute)

Initiate the step-by-step installation process:

.\AXUpdateInstaller.exe execute -runbookid="Sprint42Deploy"

The tool parses the runbook steps sequentially: pre-sync scripts, stopping IIS (w3wp.exe) and the Dynamics batch service, extracting and copying binary assemblies to the package folder (C:\AOSService\PackagesLocalDirectory), executing full database synchronization (AutoDatabaseSync.ps1), and restarting services.

Runbook Step Management & Error Recovery

During step execution, the runbook logs every operation to the RunbookWorkingFolder directory. If a step encounters an error (for example, a database synchronization failure due to a unique constraint violation on existing data):

1. The execution halts immediately, and the console displays the failed step number (e.g., Step 18 failed).
2. Open RunbookWorkingFolder and review the specific component log (e.g., AutoDatabaseSync-step18.log) to diagnose the exact root cause.
3. Resolve the underlying conflict (e.g., clean up conflicting test records in SQL Server).
4. Resume execution from the failed step using the -rerunstep parameter:

.\AXUpdateInstaller.exe execute -runbookid="Sprint42Deploy" -rerunstep=18

Alternatively, if you corrected the issue and manually executed the script outside the tool, you can instruct the installer to mark the step complete and continue to the next step:

# Advance past a resolved step
.\AXUpdateInstaller.exe execute -runbookid="Sprint42Deploy" -step=19

Inspecting and Exporting Runbook Status

To check the current status of all steps in an active or halted runbook, run:

.\AXUpdateInstaller.exe export -runbookid="Sprint42Deploy" -runbookfile="ExportedStatus.xml"

Opening ExportedStatus.xml displays each step number, description, execution state (NotStarted, InProgress, Completed, or Failed), and error codes.

---

4. Realistic Enterprise Scenario Walk-Through

Scenario: Contoso Manufacturing Enterprise Release & Emergency Hotfix Triage

Contoso Manufacturing prepares to release Sprint 42, which includes critical updates to custom Advanced Warehouse Management (WMS) models, alongside an emergency cumulative tax compliance hotfix from Microsoft. Contoso maintains a Tier 1 build virtual machine, a Tier 2 UAT sandbox, a Tier 4 performance sandbox, and a multi-box Production environment.

Step-by-Step Technical Execution & Governance:

1. Package Consolidation via CI/CD Pipeline:

   • Rather than creating two separate deployable packages (one for custom WMS code and one for the Microsoft tax hotfix), the release engineer updates the Azure DevOps YAML build pipeline.
   • The pipeline compiles the internal ContosoWMS model, pulls the external binary hotfix package from the repository artifacts feed, and executes the Create Deployable Package MSBuild task.
   • Output: A single, consolidated Contoso_Sprint42_Consolidated.zip Software Deployable Package.

2. Developer VM Verification via Command-Line Servicing:

   • To verify that the consolidated package deploys cleanly without schema conflicts, the engineer extracts the zip file onto the Tier 1 build VM at C:\Deployments\Sprint42.
   • The engineer runs the command-line lifecycle:

     .\AXUpdateInstaller.exe list
     .\AXUpdateInstaller.exe generate -runbookid="S42Build" -topologyfile="DefaultTopologyData.xml" -servicefileslist="DefaultServiceModelData.xml" -runbooktosetup="S42-runbook.xml"
     .\AXUpdateInstaller.exe import -runbookfile="S42-runbook.xml"
     .\AXUpdateInstaller.exe execute -runbookid="S42Build"
     

   • During step 22 (AutoDatabaseSync), an error occurs due to an obsolete index on WMSLocation. The runbook halts. The engineer inspects C:\Deployments\Sprint42\RunbookWorkingFolder\AutoDatabaseSync-step22.log, drops the invalid index via SQL Server, and resumes servicing using:

     .\AXUpdateInstaller.exe execute -runbookid="S42Build" -rerunstep=22
     

   • The remaining steps finish with status Completed.

3. LCS Staging & Tier 2 Validation:

   • The verified package is uploaded to the LCS Project Asset Library under Software deployable package.
   • The release manager navigates to the Tier 2 UAT sandbox in LCS, selects Maintain > Apply updates, chooses Contoso_Sprint42_Consolidated.zip, and initiates deployment.
   • Quality assurance executes the automated Regression Suite Automation Tool (RSAT) suite and business stakeholders sign off on UAT.

4. Promotion and Production Execution:

   • The release manager returns to the LCS Asset Library, selects the package, and clicks Mark as Release Candidate.
   • In the Production environment details page, the manager schedules a servicing window under Maintain > Apply updates.
   • Prior to the window, the operations team sets recurring batch jobs (such as Master Planning and inventory recalculation) to Withhold.
   • During the window, LCS automatically executes the deployment, syncs the Azure SQL Database, restarts the AOS nodes, and reports successful completion.
   • Post-deployment smoke tests succeed, and batch jobs are placed back into Waiting status.

---

5. Real-World Exam Traps: Package Deployment & Servicing

[!WARNING] Exam Trap 1: The Direct-to-Production Fallacy On the MB-500 exam, scenarios frequently ask if a critical hotfix or custom emergency fix can be deployed directly to Production to resolve an urgent outage. The answer is always NO. Microsoft Lifecycle Services hard-blocks any package from being applied to Production unless it has been successfully deployed to a Tier 2+ environment and marked as a Release Candidate in the Asset Library.

[!WARNING] Exam Trap 2: Tool Mismatch on Multi-Box Environments Any question proposing to log into a Tier 2 UAT or Production VM via Remote Desktop and execute AXUpdateInstaller.exe is strictly incorrect. Customers do not have RDP credentials or administrative desktop access to Microsoft-managed Tier 2+ environments; only LCS self-service deployment is supported.

[!WARNING] Exam Trap 3: Single Consolidated Package vs. Multiple Individual Packages When deploying multiple custom models or combining an ISV update with internal customizations, Microsoft best practice requires building and deploying a single, consolidated deployable package. Deploying individual packages sequentially causes multiple environment downtime windows, invalidates cross-model dependencies during intermediate states, and drastically increases deployment failure risk.

[!WARNING] Exam Trap 4: Runbook Command Order Confusion Watch out for exam questions that invert the generate and import commands. You cannot import a runbook that has not yet been generated. The sequence must strictly follow: generate -> import -> execute.

[!WARNING] Exam Trap 5: Abort Action vs. Destructive Database Schema Alterations Candidates often assume clicking Abort in LCS reverses all changes. While Abort successfully rolls back application binaries and service configurations, it cannot reverse destructive database schema changes (such as dropped columns or deleted index tables). Reverting destructive database changes requires an Azure SQL Point-in-Time Restore (PITR).