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 } |