Enable-DbaFilestream - Report what the WMI provider actually returned

[andreasjordan]

Fixes #10524.

The bug

Get-FilestreamReturnValue gated its success message on a constant expression:

{ 2147021885 -or 2147945411 -or 0 } {
    "The requested operation is successful. ..."
}

$Value never appears in it. 2147021885 -or 2147945411 -or 0 is just $true, so the clause matched every code. And because switch runs every matching clause without a break, that produced three separate problems:

Return code	Before	After
2147024891 "Access denied"	Access denied and the success message	Failure / Access denied
any unlisted code	only the success message, raw value lost	Unknown, raw value kept
0 / the two 21470… codes	success	Success

default was unreachable, so an unrecognized code could never fall through to report its own value.

Enable-DbaFilestream then discarded even that, surfacing the value only when -Force was absent — and -Force is the documented non-interactive path used by the examples and every test. A refused call produced no warning, no error, and an unchanged instance.

How it showed up

On a ci-azure RESTART runner while working #10522, setting FILESTREAM level 2 left the instance at level 1 on every attempt with nothing reported. The instance came back with ServiceShareName still set to the instance-name fallback rather than the share name that was passed, so the call had changed nothing at all — and the return code that would have said why was gone.

The change

Get-FilestreamReturnValue moves into its own file under private/functions/ so it can be tested, and returns ReturnValue, Category and Message. Category is Success, Failure or Unknown.

Codes in neither list are reported as Unknown with the raw value rather than guessed at in either direction — assuming success hides a refusal, assuming failure invents an error the provider never reported. A null return value is Unknown for the same reason, since switch enters no clause at all for $null.

Enable-DbaFilestream now stops on a documented refusal and warns on an unrecognized code, both regardless of -Force. -Force should mean "do not prompt", not "do not report errors". The existing warning that changes need a service restart is unchanged.

Testing

Five unit tests cover each category, plus two edge cases worth calling out:

• a null return value — switch ($null) enters no clause, so without an explicit guard this reported Failure for a call that never returned anything
• numeric type — Invoke-CimMethod hands back a UInt32, so a comparison that only matched Int32 would push every real call down the unknown path

Against a live lab, all three filestream commands still pass: Enable-DbaFilestream 3 integration tests (levels 1 and 2 and the ShareName warning), Disable-DbaFilestream and Get-DbaFilestream unchanged. Repo compliance and structure gates: 0 failures.

Note

This does not by itself fix the level 2 failure on ci-azure — it makes the provider's reason visible so that can finally be diagnosed. The level 2 test is skipped in #10522 with a pointer to #10524; once this merges it can be unskipped to read the real return code.

🤖 Generated with Claude Code

[potatoqualitee]

I really like this, thank you