Computer: Add DeleteExistingComputerAccount parameter to DSC_Computer

[Daymarvi]

Pull Request (PR) description

When joining a domain, DSC_Computer currently deletes and recreates any existing AD computer account with the same name (Get-ADSIComputer + Remove-ADSIObject). This is destructive because it:

Changes the machine SID, breaking existing Kerberos trust relationships
Loses AD group memberships assigned to the computer account
Loses GPO links specific to the computer object
Loses AD attributes (description, managedBy, etc.)

This PR adds a new DeleteExistingComputerAccount parameter (Boolean) to control this behavior:

Value	Behavior
$true (default)	Deletes and recreates the existing computer account — historical behavior, no breaking change
$false	Skips deletion; Add-Computer reuses the existing account (resets machine password only), preserving SID, group memberships, and GPO links

Example usage

Computer JoinDomain
{
    Name                         = 'Server01'
    DomainName                   = 'Contoso'
    Credential                   = $Credential
    DeleteExistingComputerAccount = $false  # Preserve existing AD computer account
}

This Pull Request (PR) fixes the following issues

Fixes #457

Task list

• Added an entry to the change log under the Unreleased section of the
  file CHANGELOG.md. Entry should say what was changed and how that
  affects users (if applicable), and reference the issue being resolved
  (if applicable).
• Resource documentation added/updated in README.md.
• Resource parameter descriptions added/updated in README.md, schema.mof
  and comment-based help.
• Comment-based help added/updated.
• Localization strings added/updated in all localization files as appropriate.
• Examples appropriately added/updated.
• Unit tests added/updated. See DSC Community Testing Guidelines.
• Integration tests added/updated (where possible). See DSC Community Testing Guidelines.
• New/changed code adheres to DSC Community Style Guidelines.

---

This change is 

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 29cbfe99-313d-4e3d-b5c3-852bd57c236c

📥 Commits

Reviewing files that changed from the base of the PR and between 9574efb and 4f7de58.

📒 Files selected for processing (1)

• tests/Unit/DSC_Computer.Tests.ps1

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/Unit/DSC_Computer.Tests.ps1

---

Walkthrough

A new DeleteExistingComputerAccount boolean parameter (default $true) is added to the DSC_Computer resource. It is declared in the MOF schema and all four functions (Get-TargetResource, Set-TargetResource, Test-TargetResource, Assert-ResourceProperty). In Set-TargetResource, ADSI deletion of an existing computer account is now conditional on this flag; setting it to $false skips deletion and emits a verbose message. An example configuration, README documentation, a localization string, and unit tests are also included.

Changes

DSC_Computer DeleteExistingComputerAccount Feature

Layer / File(s)	Summary
MOF schema and resource parameter contracts source/DSCResources/DSC_Computer/DSC_Computer.schema.mof, source/DSCResources/DSC_Computer/DSC_Computer.psm1	Adds Boolean DeleteExistingComputerAccount; to the MOF schema and extends parameter blocks and help documentation in Get-TargetResource, Set-TargetResource, Test-TargetResource, and Assert-ResourceProperty with the new boolean defaulting to $true.
Conditional deletion logic in Set-TargetResource source/DSCResources/DSC_Computer/DSC_Computer.psm1, source/DSCResources/DSC_Computer/en-US/DSC_Computer.strings.psd1	Changes the ADSI-based existing-computer-object removal from unconditional to conditional: removes the object when $true, otherwise preserves it and writes a verbose message using the new SkippingExistingComputerObjectDeletion localization string.
Unit tests, example config, README, and changelog tests/Unit/DSC_Computer.Tests.ps1, source/Examples/Resources/Computer/8-Computer_JoinDomainKeepExistingAccount_Config.ps1, source/DSCResources/DSC_Computer/README.md, CHANGELOG.md	Two new Pester contexts assert Get-ADSIComputer and Remove-ADSIObject are not invoked when DeleteExistingComputerAccount = $false; adds an example DSC config demonstrating the flag; documents the parameter in the README; records the addition in the changelog with issue reference.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• Computer: AD object deletion before domain join issue #457: This PR directly implements the feature requested in that issue — a DeleteExistingComputerAccount parameter that makes deletion of an existing AD computer account optional during domain join, addressing the problem of unintended account deletion and simplifying permission requirements.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main change: adding a DeleteExistingComputerAccount parameter to the DSC_Computer resource.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the problem, solution, and providing clear examples of the new parameter usage.
Linked Issues check	✅ Passed	The PR fully addresses Issue #457 by implementing the proposed solution: adding a configurable DeleteExistingComputerAccount parameter (Boolean, default $true) to control whether existing AD computer accounts are deleted during domain join.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the DeleteExistingComputerAccount parameter across schema, implementation, documentation, localization, examples, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Around line 10-14: The Computer section entry describing the
DeleteExistingComputerAccount parameter is missing a required issue reference
link. Add an issue reference to the end of this changelog entry using the
required format [issue
#<issue_number>](https://github.com/<owner>/<repo>/issues/<issue_number>) where
you replace the placeholder values with the actual GitHub issue number and
repository details that correspond to this feature addition.

In `@source/DSCResources/DSC_Computer/DSC_Computer.psm1`:
- Around line 101-104: The DeleteExistingComputerAccount parameter is declared
in the function signature but is missing from the hashtable returned by
Get-TargetResource. Add the DeleteExistingComputerAccount property to the
returned hashtable in Get-TargetResource (around lines 126-136) and set it to
the current value of the $DeleteExistingComputerAccount variable to maintain the
complete resource contract and match the declared schema.
- Around line 294-297: The Write-Verbose message using the
KeepingExistingComputerObject localized string in the else block (when
DeleteExistingComputerAccount is false) implies that an AD account lookup or
discovery occurred, but this branch skips AD queries entirely. Update the
verbose message to accurately reflect that the existing computer object is being
retained without claiming any AD discovery or verification took place, ensuring
the message content matches the actual behavior when the account lookup is
bypassed.

In `@source/DSCResources/DSC_Computer/en-US/DSC_Computer.strings.psd1`:
- Line 20: The KeepingExistingComputerObject message string incorrectly asserts
that an existing computer account was "found in domain" when this message is
actually used in a code path where no AD query is performed. Update the string
to remove the misleading "found in domain" phrase and instead describe what is
actually happening - that the existing account is being kept because
DeleteExistingComputerAccount is set to false, without implying that any domain
lookup or verification was performed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1bf98980-2e57-4228-a777-8fff6b703413

📥 Commits

Reviewing files that changed from the base of the PR and between 17e10f3 and acbfe21.

📒 Files selected for processing (7)

• CHANGELOG.md
• source/DSCResources/DSC_Computer/DSC_Computer.psm1
• source/DSCResources/DSC_Computer/DSC_Computer.schema.mof
• source/DSCResources/DSC_Computer/README.md
• source/DSCResources/DSC_Computer/en-US/DSC_Computer.strings.psd1
• source/Examples/Resources/Computer/8-Computer_JoinDomainKeepExistingAccount_Config.ps1
• tests/Unit/DSC_Computer.Tests.ps1

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87%. Comparing base (17e10f3) to head (4f7de58).

Additional details and impacted files

@@         Coverage Diff         @@
##           main   #462   +/-   ##
===================================
  Coverage    86%    87%           
===================================
  Files        21     21           
  Lines      2083   2086    +3     
===================================
+ Hits       1805   1825   +20     
+ Misses      278    261   -17     

Files with missing lines	Coverage Δ
source/DSCResources/DSC_Computer/DSC_Computer.psm1	90% <100%> (+<1%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.