Course Content

Building custom Bicep Local Deploy extensions From fundamentals to publishing your first custom-ready extension 4 Lessons

Introduction to Bicep Local Deploy extensions 20 min
Creating your first Bicep Local Deploy extension 45 min
Testing your Bicep Local Deploy extension 60 min
Documentation and publishing Bicep Local Deploy extension 35 min

Course content

This course takes you from Bicep Local Deploy fundamentals to publishing custom extensions that are production-ready. The getting started module starts with an introduction to the Bicep Local Deploy framework and its architecture. It covers how custom extensions work within Bicep's ecosystem. You'll set up your development environment and verify your installation using a quick-start project.

Next, you'll be building your first complete extension, expanding on the quick-start project. From looking at the project structure to defining type models with attributes, and lastly, implementing handlers that manage the resource lifecycle.

The advanced module lessons dive deeper into testing and documentation. You'll be using the bicep-local-docgen CLI tool to validate your documentation.

Prerequisites

Before starting this course, you should have:

C# programming: Be familiar with C# syntax, classes, and properties.
PowerShell basics: Understand PowerShell commands and scripting for running build scripts and tests.
REST APIs: Basic understanding of HTTP methods (GET, POST, PUT, DELETE) and JSON.
Command-line tools: Be comfortable running CLI utilities.

Don't worry if you're missing some recommended knowledge. The course provides explanations along the way. The required knowledge is mainly for following the code examples and completing the exercises.

What you'll learn

Understand Bicep Local Deploy architecture: Learn what custom extensions are, how they extend Bicep's capabilities, and the role of Azure.Bicep.Local.Extension framework and documentation attributes.
Build complete custom extensions: Create type models with documentation attributes, implement resource handlers, and test with Bicep files and Pester.
Generate and publish documentation: Use bicep-local-docgen CLI to generate markdown documentation and validation.

By the end of this course, you'll have a production-ready Bicep Local Deploy extension, including:

Documentation
End-to-end tests
Publishing workflow

You'll understand the complete lifecycle from initial concept to a published extension that users can consume in their Bicep templates.

Plan your migration Inventory your PowerShell DSC estate and choose a path for every artifact 7 Lessons

Introduction to migrating from PowerShell DSC 4 min
Why migrate, and when not to 8 min
Inventory what you have 12 min
Build and inventory the Bindery estate 20 min
Choose a migration path 10 min
Knowledge check 5 min
Summary 3 min

Migrate configurations and resources Walk all four migration paths against one legacy estate 10 Lessons

Introduction to migrating configurations and resources 3 min
Path A: Adapt in place 12 min
Adapt the legacy configuration 15 min
Path B: Import your compiled MOFs 12 min
Convert a MOF file 15 min
Path C: From script-based to class-based 15 min
Rewrite AppEnvironment as a class 20 min
Path D: Going native 8 min
Knowledge check 5 min
Summary 3 min

Replace the LCM Own the enforcement schedule, handle reboots, and migrate credentials 9 Lessons

Introduction to replacing the LCM 3 min
Map LCM features to Microsoft DSC 12 min
Own the enforcement schedule 10 min
Reboots and cross-node coordination 10 min
Migrate credentials 10 min
Prove equivalence end to end 20 min
Pitfalls from the field 8 min
Knowledge check 5 min
Summary and next steps 5 min

Course content

This course takes you from a working PowerShell DSC estate to a Microsoft DSC estate, without a rewrite weekend and without breaking production. The planning module starts where every real migration starts: with an honest look at what you already own. You'll learn why the trajectory points to Microsoft DSC, build an inventory that classifies every resource on a machine, and use that inventory to assign each artifact to one of four migration paths.

Next, you'll walk all four paths against the same small legacy estate. You'll adapt a Configuration script into a configuration document with the resource code untouched, rescue a compiled MOF file whose source script is long gone, rewrite a script-based resource as a class-based one that runs on PowerShell 7, and learn the signals that justify a full native rewrite.

The final module deals with the part of PowerShell DSC that isn't a file: the Local Configuration Manager. You'll map every LCM behavior your estate might depend on to its Microsoft DSC equivalent, replace scheduled enforcement with something you own, move credentials out of MOF files, and run an end-to-end equivalence check that proves all three migration routes converge on the same machine state.

Prerequisites

Before starting this course, you should have:

PowerShell DSC experience: You've written Configuration blocks, compiled MOF files, and run Start-DscConfiguration at least a few times.
Microsoft DSC fundamentals: You can read a configuration document, and you've run dsc config get, dsc config test, and dsc config set against one.
PowerShell scripting: Functions, modules, module manifests, and enough class syntax to read a [DscResource()] class.
A Windows machine: With both Windows PowerShell 5.1 and PowerShell 7+ installed, plus the dsc CLI on your path. Administrator rights are needed for the machine-level environment variable used in the exercises.

Don't worry if you're rusty on the Microsoft DSC side. Each unit explains the construct before using it, and every command in the exercises is shown in full. The PowerShell DSC knowledge is the part that's hard to substitute, because this course is about translating something you already own.

[!TIP]
If you've never applied a configuration document with Microsoft DSC, work through the getting-started chapters of The Microsoft DSC Handbook or The Fundamentals of Microsoft DSC first. This course assumes the mechanics and focuses entirely on the translation.

What you'll learn

Inventory a PowerShell DSC estate: Classify configurations, compiled MOFs, script-based resources, and class-based resources, and check what each Microsoft DSC adapter can already see.
Choose a migration path per artifact: Apply a four-path decision framework — adapt in place, import MOFs, rewrite as class-based, rewrite as native — and defend the choice with cost and payoff, not preference.
Execute each path hands-on: Translate Configuration scripts into configuration documents, convert MOF files with an import extension, and port Get/Set/Test-TargetResource trios into class-based resources.
Replace the LCM: Map enforcement modes, refresh intervals, reboot policy, partial configurations, and cross-node coordination to explicit Microsoft DSC replacements that you schedule and own.
Migrate credentials safely: Retire PSDscAllowPlainTextPassword and MOF encryption certificates in favor of secureString parameters and secret extensions.

By the end of this course, you'll have migrated a complete (if small) estate end to end, including:

A migration inventory report you can run against any machine
A configuration document that replaces a Configuration script
A class-based resource ported from a script-based one
A scheduled enforcement replacement for the LCM
An equivalence check that proves the migration didn't change behavior

You'll understand the full lifecycle from "we have hundreds of MOFs and nobody remembers who wrote them" to a reviewed, tested, version-controlled Microsoft DSC estate.

The running example

Every unit uses the same fictional estate, owned by a company called Bindery. A bindery is a workshop where loose sheets are fastened together into books, which is a fair description of what a migration does: fasten an old estate to a new engine without tearing any pages.

Bindery's operations team owns:

BinderyOps, a PowerShell module containing a script-based resource named AppEnvironment that manages a machine-level environment variable.
LegacyWebServer.ps1, a Configuration script that uses AppEnvironment alongside the built-in File resource.
output\localhost.mof, the compiled artifact that the LCM actually applies.

It's small enough to follow in a single sitting and structurally identical to the thousand-line resources in your production estate.

Getting started Learn the fundamentals and set up your development environment 4 Lessons

Introduction to Microsoft Desired State Configuration (DSC) 5 min
Installing Microsoft Desired State Configuration (DSC) 10 min
Your first resource invocation 10 min
Practicing and exploring 20 min

Course content

This course takes you from the Microsoft DSC fundamentals to practical implementation. The getting started module introduces Microsoft's Desired State Configuration (DSC) cross-platform command-line tool for declarative configuration management. You'll learn the core concepts that differentiate DSC from traditional configuration management approaches, install Microsoft DSC on your system, and get hands-on experience by invoking your first DSC resource. At the end, there's room for practical exercises and a knowledge check.

What you'll learn

Understand Microsoft's DSC architecture: Learn what Desired State Configuration is, how it's different from imperative tools, and why idempotency matters.
Install and configure Microsoft DSC: Set up Microsoft DSC on Windows, Linux, or macOS, including PATH configuration and installation.
Work with DSC resources: Discover how to explore resource schemas, understand property requirements, and invoke the core resource operations (get, set, test, and delete).
Configure your registry: Gain practical experience with the Microsoft.Windows/Registry DSC resource.

-/-

Inventory what you have

You can't plan a migration without knowing what you're migrating. "We should move to Microsoft DSC someday" is not a plan. But a spreadsheet with so many rows and a decision in each one is.

A PowerShell DSC estate typically contains four kinds of artifacts, and each one migrates differently.

The four artifact types

Artifact	What it looks like	Migration concern
Configuration scripts	`.ps1` files using the `Configuration` keyword	Rewrite as configuration documents (or import MOF)
Compiled MOF files	`localhost.mof`, `webserver01.mof` on pull servers	Import extension translates them
Script-based resources	Modules with `Get`/`Set`/`Test-TargetResource` functions	Run via the 5.1 adapter, or rewrite as class-based
Class-based resources	PowerShell classes with `Get()`, `Set()`, `Test()`	Run via either adapter, mostly as-is

Start with the resources, because everything else depends on them. A configuration you can't run is a configuration whose resources didn't migrate.

Enumerate what PowerShell DSC sees

On a machine with your modules installed, the classic enumeration is:

Get-DscResource | Select-Object Name, ModuleName, Version, ImplementationDetail

The ImplementationDetail property is the important one:

ScriptBased — the module implements the Get-TargetResource, Set-TargetResource, and Test-TargetResource function trio alongside a schema MOF file.
ClassBased — it's a PowerShell class decorated with [DscResource()].
Composite resources — configurations packaged as resources. They show up too, and they need special handling covered in Module 2.

[!NOTE]
Run this in Windows PowerShell 5.1, not PowerShell 7. Get-DscResource in PowerShell 7 comes from a different module version and enumerates a different set. For inventory purposes you want the 5.1 view, because that's the view the LCM has been using.

Ask the same question from the other side

Now find out what Microsoft DSC can already see. The adapters perform this discovery for you:

dsc resource list --adapter Microsoft.Adapter/WindowsPowerShell
dsc resource list --adapter Microsoft.Adapter/PowerShell

The first command lists everything the Windows PowerShell 5.1 adapter can find — script-based and class-based resources. The second lists what the PowerShell 7+ adapter can find, which is class-based resources only.

That difference is the entire inventory in one line:

The 5.1 adapter maintains full backwards compatibility with script-based resources.
The PowerShell 7+ adapter deliberately supports only class-based resources.

If a resource shows up in the first list but not the second, you've found a migration decision point.

Figure 1: The gap between the two adapter views is your Path C backlog.

Make the inventory systematic

Comparing two console outputs by eye works for ten resources and fails for a hundred. The following script joins both views into a single migration-oriented report. Save it as Get-DscMigrationInventory.ps1.

# Get-DscMigrationInventory.ps1
[CmdletBinding()]
param()

$legacy = Get-DscResource -ErrorAction SilentlyContinue

$adapted = dsc resource list --adapter Microsoft.Adapter/WindowsPowerShell --output-format json |
    ConvertFrom-Json

$adaptedPs7 = dsc resource list --adapter Microsoft.Adapter/PowerShell --output-format json |
    ConvertFrom-Json

foreach ($resource in $legacy) {
    $moduleName = if ($resource.ModuleName) { $resource.ModuleName } else { '(binary)' }
    $adaptedType = '{0}/{1}' -f $moduleName, $resource.Name

    [PSCustomObject]@{
        Resource        = $adaptedType
        Implementation  = $resource.ImplementationDetail
        VisibleTo51     = ($adapted.type -contains $adaptedType)
        VisibleToPs7    = ($adaptedPs7.type -contains $adaptedType)
        SuggestedPath   = if ($adaptedPs7.type -contains $adaptedType) {
            'Adapt (PowerShell 7+)'
        } elseif ($adapted.type -contains $adaptedType) {
            'Adapt (5.1), consider class-based rewrite'
        } else {
            'Investigate: not discovered by any adapter'
        }
    }
}

[!NOTE]
This is the same inventory script used in The Microsoft DSC Handbook, Chapter 11. If you own the book, you'll recognize it; if you don't, the script above is complete and you don't need anything else.

Read the script in three parts:

$legacy is the classic view with every resource Windows PowerShell can find on $env:PSModulePath.
$adapted and $adaptedPs7 are the two adapter views, requested as JSON so they can be queried rather than read.
The loop builds the Module/Resource type string that a configuration document would use, then checks it against both adapter views.

Run it and you get a table that classifies every resource on the machine:

Resource                                Implementation VisibleTo51 VisibleToPs7 SuggestedPath
--------                                -------------- ----------- ------------ -------------
BinderyOps/AppEnvironment               ScriptBased    True        False        Adapt (5.1), consider class-based rewrite
PSDesiredStateConfiguration/File        Binary         True        False        Adapt (5.1), consider class-based rewrite
BinderyOps/AppRegistration              ClassBased     True        True         Adapt (PowerShell 7+)

The SuggestedPath column is a starting point, not a verdict. A resource that the PowerShell 7+ adapter can see might still deserve a native rewrite; a resource stuck on 5.1 might be scheduled for deletion instead. But the column turns a vague intention into a concrete list you can walk through in a planning meeting.

[!WARNING]
Get-DscResource in Windows PowerShell enumerates from $env:PSModulePath as seen by 5.1, while dsc resource list goes through the adapter's own discovery. If the two disagree on what exists, check which module paths each host sees before assuming a resource is broken. This is by far the most common source of "it works in PowerShell but DSC can't find it" reports.

Inventory the rest of the estate

Resources are the hard part, but three more sweeps complete the picture:

Configuration scripts. Search your repositories for the Configuration keyword:

Get-ChildItem -Path .\ -Filter *.ps1 -Recurse |
    Select-String -Pattern '^\s*Configuration\s+\w+' |
    Select-Object Path, Line

For each hit, record which resources it imports and whether the script is still the source of truth for a compiled MOF somewhere.

Compiled MOFs. On a pull server, the configuration store is the authoritative list. Locally, they're wherever your build wrote them:

Get-ChildItem -Path .\ -Filter *.mof -Recurse |
    Select-Object FullName, LastWriteTime, Length

The LastWriteTime matters more than you'd expect. A MOF compiled four years ago whose source script no longer exists is a Path B candidate. A MOF regenerated by last night's build is a Path A candidate and plan to migrate the script instead.

Hidden cross-node dependencies. These bite late, so find them early:

Get-ChildItem -Path .\ -Filter *.ps1 -Recurse |
    Select-String -Pattern 'WaitFor(All|Any|Some)'

Every hit is a piece of orchestration logic that has no direct equivalent in Microsoft DSC. Module 3 explains what to do with them. For now, just know they exist.

What good looks like

A finished inventory answers four questions for every row:

What is it? Artifact type and implementation detail.
Who owns it? A team name, not "operations."
Is it still used? Last applied, last compiled, last modified.
Which path? One of the four you'll meet in unit 5.

The fourth column is the one this course exists to fill. The first three are yours, and they're worth more than they look: a surprising share of every real migration is deleting things nobody had the authority to delete before.

> EOF