AzureDevOpsDscNative.psd1

@{
    RootModule           = 'AzureDevOpsDscNative.psm1'

    # Version number of this module.
    #
    # This value is a fallback for local and CI builds only. Released versions are
    # driven by the git tag: the publish workflow sets $env:ModuleVersion from the
    # tag, and the build stamps that value into the packaged manifest instead of this
    # one. Do not hand-edit this to cut a release - push a vX.Y.Z tag.
    moduleVersion      = '2.0.0'

    # ID used to uniquely identify this module
    GUID                 = 'e7eb078e-5e97-42be-ae8f-decb140fc38e'

    # Author of this module
    Author               = 'ZanattaMichael'

    # Company or vendor of this module
    CompanyName          = 'ZanattaMichael'

    # Copyright statement for this module
    Copyright            = 'Copyright the DSC Community contributors and ZanattaMichael. All rights reserved.'

    # Description of the functionality provided by this module
    Description          = 'A fork of the DSC Community AzureDevOpsDsc module with native DSC v3 support: every resource is discoverable and invokable by dsc.exe via the Microsoft.Adapter/PowerShell adapter, using generated adapted resource manifests, without requiring a wrapper resource.'

    # Minimum version of the Windows PowerShell engine required by this module
    PowerShellVersion  = '7.0'

    # Minimum version of the common language runtime (CLR) required by this module
    CLRVersion           = '4.0'

    # Functions to export from this module
    #FunctionsToExport = @()

    # Cmdlets to export from this module
    #CmdletsToExport = @()

    # Variables to export from this module
    VariablesToExport    = @()

    # Aliases to export from this module
    AliasesToExport      = @()

    # Import all the 'DSCClassResource', modules as part of this module
    NestedModules        = @()

    DscResourcesToExport = @('AzDoGroupPermission','AzDoOrganizationGroup','AzDoProject','AzDoProjectServices','AzDoProjectGroup','AzDoGroupMember','AzDoGitRepository','AzDoGitPermission','AzDoAreaPermission','AzDoIterationPermission','AzDoWIPTags','AzDoAreaNodes','AzDoIterationNodes','AzDoBranchPolicy','AzDoVariableGroup','AzDoServiceConnection','AzDoPipelineEnvironment','AzDoAgentPool','AzDoAgentQueue','AzDoTeam','AzDoTeamMember','AzDoPipeline','AzDoPipelinePermission','AzDoEnvironmentApproval','AzDoVariableGroupPermission','AzDoServiceConnectionPermission','AzDoAgentPoolPermission','AzDoSecurityNamespacePermission','AzDoArtifactFeed','AzDoArtifactFeedPermission','AzDoDeploymentGroup','AzDoTaskGroup','AzDoOrganizationSettings','AzDoExtension','AzDoAuditStream','AzDoProjectPermission','AzDoEnvironmentPermission','AzDoWiki','AzDoNotificationSubscription','AzDoRepositorySettings','AzDoCheckConfiguration','AzDoTeamSettings','AzDoArtifactFeedSettings','AzDoArtifactFeedView','AzDoProcess','AzDoProcessPermission','AzDoUserEntitlement','AzDoServiceHook','AzDoPipelineSettings','AzDoQueryFolder','AzDoWorkItemQuery','AzDoQueryPermission','AzDoWIPTagHygiene','AzDoSecureFile','AzDoSecureFilePermission','AzDoPipelineFolder','AzDoPipelineFolderPermission','AzDoGroupEntitlement','AzDoServicePrincipalEntitlement','AzDoPicklist','AzDoProcessWorkItemType','AzDoProcessField','AzDoProcessState','AzDoProcessRule','AzDoProcessBehavior','AzDoPipelineAuthorization','AzDoEnvironmentKubernetesResource','AzDoEnvironmentVMResource','AzDoDeploymentGroupTarget','AzDoReleaseFolder','AzDoReleaseFolderPermission','AzDoReleaseDefinitionPermission','AzDoTestVariable','AzDoTestConfiguration','AzDoTestPlan','AzDoTestSuite','AzDoBuildRetentionSettings','AzDoWikiPage','AzDoTaggingPermission','AzDoAnalyticsPermission','AzDoAnalyticsViewsPermission','AzDoDashboard','AzDoOrganizationPermission','AzDoTaskGroupPermission')

    RequiredAssemblies   = @()

    # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
    PrivateData          = @{

        PSData = @{
            # Set to a prerelease string value if the release should be a prerelease.
            Prerelease   = 'preview1'

            # Tags applied to this module. These help with module discovery in online galleries.
            Tags         = @('DesiredStateConfiguration', 'DSC', 'DSCResourceKit', 'DSCResource', 'DSCv3', 'AzureDevOps')

            # A URL to the license for this module.
            LicenseUri   = 'https://github.com/ZanattaMichael/AzureDevOpsDsc/blob/main/LICENSE'

            # A URL to the main website for this project.
            ProjectUri   = 'https://github.com/ZanattaMichael/AzureDevOpsDsc'

            # A URL to an icon representing this module.
            IconUri      = 'https://dsccommunity.org/images/DSC_Logo_300p.png'

            # ReleaseNotes of this module.
            # Per-release notes are generated from the CHANGELOG's [Unreleased] section
            # at build time and attached to the GitHub Release. This link is the fallback
            # shown on the Gallery listing.
            ReleaseNotes = '## [2.0.0-preview1] - 2026-11-15
 
### Removed
 
- **BREAKING:** `New-AzDoAuthenticationProvider` no longer has the plain-text
  `-PersonalAccessToken` (alias `-PAT`) and `-ClientSecret` parameters, which only warned
  until now. Pass `-SecureStringPersonalAccessToken` or `-SecureStringClientSecret`, for
  example `ConvertTo-SecureString -String $env:AZDO_PAT -AsPlainText -Force` or
  `Read-Host -AsSecureString`.
 
- Unused code
  - Removed private functions that nothing called: `Resolve-ACLToken`,
    `New-AzDevOpsACLToken` and `Format-DescriptorType`, with their unit tests.
  - Removed `Write-Log.ps1`, `Initialize-Log.ps1` and `Flush-Log.ps1`, which
    held only commented-out code but were still read on every module import,
    and `Initalize-AzDevOpsCache.ps1`, whose function (`Initialize-Cache`) was
    never exported under that name and was not called.
 
### Added
 
- Secret references. Wherever a resource takes a secret, a configuration can give
  `@{ SecretEnvironmentVariable = ''NAME'' }` or `@{ SecretName = ''Name''; SecretVault = ''Vault'' }`
  (Microsoft.PowerShell.SecretManagement) instead of the secret, so it no longer has to be
  written into the configuration document or the MOF. Accepted for `AzDoVariableGroup`
  variables, values in `AzDoServiceConnection` `Authorization`, values in the
  `ConsumerInputs` of `AzDoServiceHook` and `AzDoAuditStream`, and `AzDoPipeline` variable
  values. A reference that cannot be resolved fails the resource. Literal values still
  work. See ''Keeping Secrets out of a Configuration'' in `USAGE.md`.
 
- CI
  - `Create Tag` workflow (`.github/workflows/create-tag.yml`), run manually from the
    Actions tab. It creates and pushes an annotated version tag on `main` (or a given
    branch or commit contained in `main`). The tag is either supplied (`vX.Y.Z` or
    `vX.Y.Z-<prerelease>`) or derived by bumping the patch, minor or major part of the
    highest existing `vX.Y.Z` tag. An existing tag is never moved. Because a tag pushed
    with `GITHUB_TOKEN` does not trigger other workflows, creating a tag this way does
    not cut a release unless the `publish` option is ticked, which dispatches the
    Publish workflow on the new tag.
 
### Changed
 
- **BREAKING:** credential storage
  - `New-AzDoAuthenticationProvider` fails, and writes no credential, when it cannot
    restrict the permissions of `AZDODSC_CACHE_DIRECTORY` or `ModuleSettings.clixml`. It
    used to warn and write the credential anyway.
  - On Linux and macOS, `ModuleSettings.clixml` is only read when the cache directory is
    owned by the current account (or root) and has no group or other permissions. A
    directory that fails the check stops the run with the fix (`chmod 700`). Set
    `AZDODSC_ALLOW_SHARED_CACHE_DIRECTORY=1` to get a warning instead, for a mounted
    volume whose permissions cannot be changed.
  - `ModuleSettings.clixml` no longer holds the access token for service principal,
    certificate, Azure CLI and file or GitHub Actions workload identity sign-in: restoring
    any of them already requested a new token. A managed identity access token is kept on
    Windows, where the file is DPAPI-encrypted, and no longer written on Linux and macOS,
    where a later session asks the identity endpoint again. A personal access token and a
    manually supplied federated token are stored as before, since nothing else can
    reproduce them.
 
- Build
  - `Resolve-Dependency.psd1` pins `PSResourceGetVersion` to `1.2.0`. It was
    unset, so the bootstrap downloaded the newest PSResourceGet on every run,
    and with `1.3.1` the first `Save-PSResource` fails with `Response returned
    status code package: Not Found`, which stopped the build and unit test
    workflows before any module code ran.
- Performance
  - Cache lookups are about three times faster. `Get-CacheObject` reads the
    cache variable once instead of twice and no longer builds a directory path
    it never used, `Get-CacheKeyIndex` no longer walks the whole cache while
    binding its parameter, and `Get-CacheObject`, `Add-CacheItem`,
    `Remove-CacheItem` and `Get-CacheKeyIndex` only call `Write-Verbose` when
    verbose output is on or `AZDO_VERBOSELOGGING_FILEPATH` is set. With a
    5,000-item cache, 1,000 `Get-CacheItem` calls take about 0.55 s instead
    of 2 s, and filling a 5,000-item cache with `Add-CacheItem` takes about
    2 s instead of 3.5 s.
  - `Add-CacheItem` replaces an existing key through the key index instead of
    scanning the whole cache: 1,000 replacements in a 5,000-item cache take
    about 1 s instead of 3.7 s.
  - `Refresh-CacheObject` no longer reads a cache file back in when the cache
    in memory is exactly what this session last wrote to, or read from, that
    file. `New-` and `Set-` functions export a cache and then refresh it, so
    each one read back the file it had just written. `Export-CacheObject`,
    `Set-CacheObject` and `Import-CacheObject` record the file''s last write
    time and length with the items involved (new private helpers
    `Set-CacheFileStamp` and `Test-CacheFileStamp`); a file changed by another
    process, or a cache changed in memory since, is reloaded as before. For a
    5,000-item cache this saves about 150 ms per `New-`/`Set-` call. Within
    the same session the cached values are then the objects that were added,
    not copies that have been through `Export-Clixml` and `Import-Clixml`.
    `CONTRIBUTING.md` and `CLAUDE.md` describe this and the verbose guard.
  - `Find-Identity` scans the group, user and service-principal caches with a
    plain loop instead of invoking a filter scriptblock for every cached
    identity. It runs once per ACE, so this is the largest part of formatting
    an ACL: with 2,000 identities in each cache a lookup takes about a third of
    the time it did. What it returns, and what it warns about, is unchanged.
  - `ConvertTo-FormattedACL` resolves each ACE descriptor once per call rather
    than once per ACE. A namespace holds far more ACEs than distinct identities,
    so formatting 300 ACLs that share 20 identities went from about 7.5 seconds
    to under one. A descriptor that does not resolve is remembered for the rest
    of the call as well, so the ACEs a deleted identity leaves behind cost one
    API lookup and one warning per call instead of one for every ACE.
  - `AzDoAPI_3_GroupMemberCache` matches each group''s member descriptors
    through a set instead of testing every cached user and group against the
    member list with `-in`. Building the cache for 400 groups and 1,500 users
    went from 9.4 seconds to 0.75 (excluding the API calls), with the same
    members in the same order.
  - `AzureDevOpsDsc.Common` imports faster, which matters because DSC imports
    the module again for each resource invocation. The function files are
    enumerated with `System.IO` instead of `Get-ChildItem -Recurse -Include`,
    the public functions are exported in one `Export-ModuleMember` call instead
    of one call each, and the cache initializers, which two of the listed
    directories both reach, are dot-sourced once. The functions defined and
    exported are the same.
  - A resource instance keeps the authentication token its session already
    holds when that token is unexpired and was issued for the organization and
    identity in `ModuleSettings.clixml`
    (`[AzDevOpsDscResourceBase]::CanReuseAuthenticationToken()`). Until now
    every instance acquired a new one - a request to Microsoft Entra ID or the
    identity endpoint, or a new `az` process - so an export paid that for each
    exported instance. A personal access token is never kept this way, and a
    session that holds no token, such as the fresh runspace `Invoke-DscResource`
    starts, restores it exactly as before.
  - `AzDoWIPTagHygiene`: `Get-AzDoTagMisalignment` works out each canonical
    tag''s normalized and digit-free forms once instead of once for every live
    tag it is compared with, and skips the edit distance for a pair whose
    lengths alone put it below `SimilarityThreshold`. Matching 982 live tags
    against 100 canonical tags went from about 16 seconds to about 2. The
    misalignments reported, their scores and their order are unchanged.
  - `AzDoIterationNodes`: `Get-AzDoIterationNodes` and
    `Format-AzDoIterationNodes` match nodes by path through an index instead of
    scanning the other list for every node. With 750 desired iterations in a
    project that has 750, `Get` went from about 7.7 seconds to under one.
  - `AzDoAreaNodes`: `Get-AzDoAreaNodes` clears the project''s stale entries
    from the area node cache in one pass rather than rescanning the cache for
    every node. Reading a project with about 1,300 area nodes went from about
    4.8 seconds to about 1.5 (excluding the API call).
  - `AzDoAreaNodes`, `AzDoAreaPermission` and `AzDoIterationNodes`:
    `Get-AllAzDoClassificationNodePaths` collects the parent paths through a
    set rather than searching, and copying, an array for each one.
  - `AzDoGroupMember`: `Get-AzDoGroupMember` pairs each membership difference
    with its identity through an index by `originId`. Comparing 1,300 desired
    members with 1,400 live ones went from about 3.3 seconds to under 0.1.
  - `AzDoTestSuite`: `Get-AzDoTestSuite` hands the suite a missing suite has
    to be created under to `New-AzDoTestSuite` as `LookupResult.parentSuiteId`,
    so creating a suite no longer lists the project''s test plans and the
    plan''s suites a second time.
  - `AzDoTestConfiguration`: `Get-AzDoTestConfiguration` hands the `Values` it
    has already validated and parsed to `New-`/`Set-AzDoTestConfiguration` as
    `LookupResult.parsedValues`, so neither lists the project''s test variables
    a second time.
  - Every resource: `DscResourceBase` remembers, per '


        } # End of PSData hashtable

    } # End of PrivateData hashtable
}