diff --git a/.github/workflows/build-and-release.yml b/.github/workflows/build-and-release.yml index 0eabc16..e9f757d 100644 --- a/.github/workflows/build-and-release.yml +++ b/.github/workflows/build-and-release.yml @@ -4,7 +4,7 @@ on: workflow_dispatch: inputs: publish: - description: Publish the verified release candidate to PowerShell Gallery + description: Publish to PowerShell Gallery and create a tagged GitHub prerelease required: true type: boolean default: false @@ -16,8 +16,8 @@ jobs: verify-release-candidate: uses: ./.github/workflows/verify-package.yml - publish: - name: Publish the verified artifact + publish-gallery: + name: Publish the verified artifact to PowerShell Gallery if: ${{ inputs.publish && github.ref == 'refs/heads/main' }} needs: verify-release-candidate runs-on: ubuntu-latest @@ -45,6 +45,9 @@ jobs: env: POWERSHELL_GALLERY_API_KEY: ${{ secrets.POWERSHELL_GALLERY_API_KEY }} run: | + if ([string]::IsNullOrWhiteSpace($env:POWERSHELL_GALLERY_API_KEY)) { + throw 'POWERSHELL_GALLERY_API_KEY is not configured in the PowerShell Gallery environment.' + } $package = @(Get-ChildItem ./output/packages -Filter '*.nupkg' -File) $checksum = @(Get-ChildItem ./output/packages -Filter '*.sha256' -File) if ($package.Count -ne 1 -or $checksum.Count -ne 1) { @@ -60,3 +63,78 @@ jobs: -Force Publish-PSResource -NupkgPath $package[0].FullName ` -Repository PSGallery -ApiKey $env:POWERSHELL_GALLERY_API_KEY + + publish-github-release: + name: Create the GitHub prerelease + if: ${{ inputs.publish && github.ref == 'refs/heads/main' }} + needs: publish-gallery + runs-on: ubuntu-latest + permissions: + contents: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Download validated package + uses: actions/download-artifact@v4 + with: + name: PSDataverse-2-rc + path: output/packages + + - name: Read release identity + id: release + shell: pwsh + run: | + $package = @(Get-ChildItem ./output/packages -Filter '*.nupkg' -File) + $checksum = @(Get-ChildItem ./output/packages -Filter '*.sha256' -File) + if ($package.Count -ne 1 -or $checksum.Count -ne 1) { + throw 'The validated artifact must contain one package and one checksum.' + } + $expectedHash = ((Get-Content $checksum[0].FullName -Raw) -split '\s+')[0] + $actualHash = (Get-FileHash $package[0].FullName -Algorithm SHA256).Hash + if ($actualHash -ne $expectedHash) { + throw "Package checksum mismatch: expected $expectedHash; got $actualHash." + } + + $archive = [IO.Compression.ZipFile]::OpenRead($package[0].FullName) + try { + $nuspecEntry = @($archive.Entries | Where-Object FullName -Like '*.nuspec') + if ($nuspecEntry.Count -ne 1) { + throw "Expected one nuspec; found $($nuspecEntry.Count)." + } + $reader = [IO.StreamReader]::new($nuspecEntry[0].Open()) + try { [xml]$nuspec = $reader.ReadToEnd() } finally { $reader.Dispose() } + } + finally { + $archive.Dispose() + } + + $name = [string]$nuspec.package.metadata.id + $version = [string]$nuspec.package.metadata.version + if ($name -ne 'PSDataverse' -or $version -notmatch '-') { + throw "Expected a PSDataverse prerelease package; found '$name' '$version'." + } + $notesPath = "docs/releases/$version.md" + if (!(Test-Path -LiteralPath $notesPath -PathType Leaf)) { + throw "Release notes '$notesPath' were not found." + } + + "version=$version" >> $env:GITHUB_OUTPUT + "tag=v$version" >> $env:GITHUB_OUTPUT + "package=$($package[0].FullName)" >> $env:GITHUB_OUTPUT + "checksum=$($checksum[0].FullName)" >> $env:GITHUB_OUTPUT + "notes=$notesPath" >> $env:GITHUB_OUTPUT + + - name: Create tagged GitHub prerelease + shell: pwsh + env: + GH_TOKEN: ${{ github.token }} + run: | + gh release create '${{ steps.release.outputs.tag }}' ` + '${{ steps.release.outputs.package }}' ` + '${{ steps.release.outputs.checksum }}' ` + --title 'PSDataverse ${{ steps.release.outputs.version }}' ` + --notes-file '${{ steps.release.outputs.notes }}' ` + --target '${{ github.sha }}' ` + --prerelease diff --git a/LICENSE b/LICENSE index f627ad5..4c227ab 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2022 Reza Niroomand +Copyright (c) 2022-2026 Reza Niroomand Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index fed04b7..c3bede2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,24 @@ -# Table of Contents +# PSDataverse + +![PSDataverse logo](media/PSDataverse-Logo.png) + +[![PowerShell Gallery](https://img.shields.io/powershellgallery/v/PSDataverse?include_prereleases&label=PowerShell%20Gallery)](https://www.powershellgallery.com/packages/PSDataverse) +[![Downloads](https://img.shields.io/powershellgallery/dt/PSDataverse)](https://www.powershellgallery.com/packages/PSDataverse) +[![Build and test](https://github.com/rezanid/PSDataverse/actions/workflows/build-and-test.yml/badge.svg?branch=main)](https://github.com/rezanid/PSDataverse/actions/workflows/build-and-test.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +High-performance, pipeline-friendly PowerShell access to Microsoft Dataverse. + +> [!IMPORTANT] +> PSDataverse `2.0.0-rc.1` is a public release candidate requiring PowerShell +> 7.6 or later. It contains intentional breaking changes from 0.x; review the +> [migration guide](MIGRATION.md) before upgrading production automation. + +See [what is new in PSDataverse 2.0.0-rc.1](docs/releases/2.0.0-rc.1.md), the +[complete command reference](docs/reference/README.md), and the +[measured write-transport guide](docs/guides/choosing-a-write-transport.md). + +## Table of Contents * [What is PSDataverse](#what-is-psdataverse) * [Features](#features) * [How to install](#how-to-install) @@ -7,26 +27,46 @@ * [Sending operations to Dataverse](#sending-operations-to-dataverse) # What is PSDataverse? -PSDataverse is a PowerShell module that brings Dataverse's Web API to PowerShell 7+ with features like piping, batching and more. It is designed with ease-of-use and performance in mind and follows the patterns of native PowerShell cmdlets to play nicely with other modules. - -> [!IMPORTANT] -> PSDataverse 2 modernization is in progress. See the [implementation plan](docs/PSDataverse-2-plan.md) and [0.x migration guide](MIGRATION.md). The current development build requires PowerShell 7.6 or later. +PSDataverse brings Microsoft Dataverse's Web API to PowerShell with secure +authentication, first-class connection objects, controlled concurrency, batching, +bulk operations, and commands designed for composition in PowerShell pipelines. The [command reference](docs/reference/README.md) is the source for the detailed help packaged with the module and lists its syntax, examples, pipeline support, and aliases. For write-heavy workloads, see [choosing a write transport](docs/guides/choosing-a-write-transport.md). # Features -* Securely connect to Dataverse. -* Supports batching. -* Supports parallelism. -* Automatically reconnects when authentication token is about to expire. -* Enhanced pipeline support (accepts different data types as input and emits responses to the pipeline). -* Automatic wait-and-retry for transient errors by default. -* Respects throttling data sent by Dataverse. -* Does not hide the response sent back by Dataverse. +* Authenticate with WAM, system browser, device code, IWA, client secrets, + certificates, access tokens, token providers, or compatible connection strings. +* Keep named Dataverse connections and choose an explicit default connection. +* Run individual requests through a bounded, cancellation-aware parallel scheduler. +* Send concurrent `$batch` envelopes or CreateMultiple, UpdateMultiple, and + UpsertMultiple workloads with explicit chunking and degree of parallelism. +* Use pipeline-friendly CRUD, metadata, action/function, import, and export commands. +* Honor Dataverse concurrency hints and transient retry guidance while avoiding + unsafe automatic replay of ambiguous writes. +* Diagnose failed batch and multiple-operation rows without hiding Dataverse's + original response. +* Run the same verified package on Windows, Linux, and macOS. # How to install -You can install the [PSDataverse module directly from PowerShell Gallery](https://www.powershellgallery.com/packages/PSDataverse) using the following command + +Install the PSDataverse 2 release candidate from +[PowerShell Gallery](https://www.powershellgallery.com/packages/PSDataverse) with +PSResourceGet: + +```powershell +Install-PSResource -Name PSDataverse -Version 2.0.0-rc.1 -Prerelease +``` + +Or use PowerShellGet: + +```powershell +Install-Module -Name PSDataverse -RequiredVersion 2.0.0-rc.1 -AllowPrerelease +``` + +The following command continues to install the latest stable 0.x release until +PSDataverse 2 reaches general availability: + ```powershell Install-Module -Name PSDataverse ``` diff --git a/docs/PSDataverse-2-plan.md b/docs/PSDataverse-2-plan.md index 5917df6..962731e 100644 --- a/docs/PSDataverse-2-plan.md +++ b/docs/PSDataverse-2-plan.md @@ -83,7 +83,7 @@ The read-only and disposable-table write results are recorded in `docs/benchmark - [x] Detect and report whether a table supports each multiple-operation message before sending a large workload. - [x] Complete command help, measured transport recommendations, and the 0.x-to-2.x migration guide. - [x] Produce and verify deterministic prerelease packages, including installation from a local PowerShell repository. -- [ ] Run the release-candidate package on Windows, Linux, and macOS with PowerShell 7.6. +- [x] Run the release-candidate package on Windows, Linux, and macOS with PowerShell 7.6. Milestone 4 is complete when the .NET 10 package passes unit, packaged-module, integration, vulnerability, deterministic-build, and cross-platform PowerShell 7.6 @@ -137,6 +137,10 @@ PSResourceGet repository into an isolated module path and smoke-tested with PowerShell 7.6. The manual release workflow uploads this verified artifact and can publish only that same file through an explicit workflow input. +The release-candidate workflow passed on Windows, Linux, and macOS in both pull +request verification and the post-merge `main` run on September 11, 2026. This +completed Milestone 4. + ## Compatibility policy - Preserve concepts and common scripts where doing so does not retain a defect or insecure behavior. diff --git a/docs/releases/2.0.0-rc.1.md b/docs/releases/2.0.0-rc.1.md new file mode 100644 index 0000000..46f6bd7 --- /dev/null +++ b/docs/releases/2.0.0-rc.1.md @@ -0,0 +1,116 @@ +# PSDataverse 2.0.0-rc.1 + +PSDataverse 2 is a substantial modernization of the high-performance PowerShell +module for Microsoft Dataverse. This release candidate keeps the recognizable +low-level Web API model while adding safer authentication, first-class connections, +bounded concurrency, structured diagnostics, and a broad PowerShell-native command +surface. + +This is a public prerelease. Please test important automation in a non-production +environment and report feedback through +[GitHub Issues](https://github.com/rezanid/PSDataverse/issues). + +## Install + +PSDataverse 2 requires PowerShell 7.6 or later. + +```powershell +Install-PSResource -Name PSDataverse -Version 2.0.0-rc.1 -Prerelease +``` + +PowerShellGet users can install it with: + +```powershell +Install-Module -Name PSDataverse -RequiredVersion 2.0.0-rc.1 -AllowPrerelease +``` + +Review the [0.x migration guide](https://github.com/rezanid/PSDataverse/blob/main/MIGRATION.md) +before upgrading existing automation. + +## Highlights + +### Authentication and connections + +- Interactive authentication uses Windows Web Account Manager where available and + the system browser elsewhere, including passwordless and passkey experiences + offered by the identity platform. +- Device code, Integrated Windows Authentication, client secret, certificate, + supplied access token, token provider, and compatible legacy connection-string + flows are supported. +- Connections are first-class objects. Scripts can create, inspect, select, switch, + refresh, and dispose named connections without relying on undocumented globals. +- Concurrent requests coalesce token refresh instead of acquiring duplicate tokens. + +### Performance without hidden semantics + +- A bounded `System.Threading.Channels` scheduler replaces polling-based task + coordination and provides backpressure, cancellation, response-order controls, + and explicit degrees of parallelism. +- Individual requests, concurrent `$batch` envelopes, and CreateMultiple, + UpdateMultiple, and UpsertMultiple remain explicit choices because they have + different ordering, transaction, and failure semantics. +- Dataverse `x-ms-dop-hint` and `Retry-After` guidance are respected. +- Ambiguous writes are not silently replayed. +- Multiple-operation capability checks are cached per connection and avoid sending + large unsupported workloads. + +In the disposable test environment, five concurrent 20-operation batch envelopes +reached a median 165.52 POST operations/second, versus 57.76 for individual requests +at DOP 20. Two concurrent 50-row bulk envelopes reached a median 131.85 PATCH +operations/second, versus 51.12 for individual requests at DOP 20. These measurements +are workload-specific starting points, not universal defaults. See the +[benchmark and methodology](https://github.com/rezanid/PSDataverse/blob/main/docs/benchmarks/2026-09-org8848d2a1.md) +and [transport-selection guide](https://github.com/rezanid/PSDataverse/blob/main/docs/guides/choosing-a-write-transport.md). + +### PowerShell-native commands + +- `Invoke-DataverseRequest` is the preferred low-level command; + `Send-DataverseOperation` remains as a compatibility alias. +- New commands cover connection inspection, WhoAmI testing, row CRUD, table + metadata and provisioning, actions and functions, CSV/JSON import and export, + and Dataverse multiple-operation messages. +- Every exported command ships with generated, schema-validated external help, + examples, pipeline metadata, and an online Markdown reference. + +### Actionable failures and safer behavior + +- Batch responses are parsed deterministically, including malformed proxy bodies, + mixed line endings, duplicate headers, throttling responses, and failed content + IDs. +- Multiple-operation failures identify the failed chunk, source row range, retained + input objects, failed content IDs, and successful sibling chunks without exposing + row contents in the displayed error message. +- Cancellation flows through requests, pagination, batches, retry delays, and + scheduler waits. +- Successful non-200 responses retain their bodies and content headers. +- Long-standing defects in change-set removal, row counts, option-set export, and + connection isolation are corrected. + +## Runtime and release quality + +- Targets .NET 10 and requires PowerShell 7.6. +- Supports Windows, Linux, and macOS; Integrated Windows Authentication remains + available for compatible federated identities, while WAM is recommended for + managed Entra identities on Windows. +- Removes the unused Scriban/Humanizer feature and dependencies. +- Builds twice from clean Release directories and requires matching module-file and + canonical package hashes. +- Installs the generated package through an isolated local repository and smoke-tests + it outside the source tree. +- Passes .NET tests, packaged Pester tests, static analysis, dependency vulnerability + auditing, guarded live Dataverse integration tests, and PowerShell 7.6 package + installation on Windows, Linux, and macOS. + +## Breaking changes + +- PowerShell 5.1 and PowerShell 7.4 are not supported by the PSDataverse 2 binary. +- Scripts should retain and pass the connection returned by `Connect-Dataverse` + instead of reading undocumented global variables. +- New scripts should choose an explicit authentication flow. +- Write replay, output ordering, and concurrency are more explicit to avoid hidden + correctness risks. +- The unexported experimental `Connect-DataverseNew` and unused Scriban-based + `ConvertTo-CustomText` implementation were removed. + +The complete compatibility table and runnable replacements are in the +[migration guide](https://github.com/rezanid/PSDataverse/blob/main/MIGRATION.md). diff --git a/media/PSDataverse-GalleryIcon.png b/media/PSDataverse-GalleryIcon.png new file mode 100644 index 0000000..bb87a61 Binary files /dev/null and b/media/PSDataverse-GalleryIcon.png differ diff --git a/src/Module/PSDataverse.psd1 b/src/Module/PSDataverse.psd1 index 2983bb7..791e196 100644 --- a/src/Module/PSDataverse.psd1 +++ b/src/Module/PSDataverse.psd1 @@ -22,13 +22,13 @@ GUID = '081185a0-92be-4624-85e8-4903acb07e03' Author = 'Reza Niroomand' # Company or vendor of this moduled -CompanyName = 'Novovio' +CompanyName = 'Reza Niroomand' # Copyright statement for this module -Copyright = 'Copyright (c) Novovio.' +Copyright = 'Copyright (c) 2022-2026 Reza Niroomand.' # Description of the functionality provided by this module -Description = 'Bring Dataverse''s Web API to PowerShell.' +Description = 'High-performance PowerShell access to Microsoft Dataverse Web API with secure authentication, parallel requests, batching, bulk operations, and pipeline-friendly commands.' # Minimum version of the PowerShell engine required by this module PowerShellVersion = '7.6' @@ -102,7 +102,17 @@ PrivateData = @{ PSData = @{ # Tags applied to this module. These help with module discovery in online galleries. - Tags = @('PSEdition_Core', 'Windows', 'Linux', 'macOS', 'Dataverse') + Tags = @( + 'PSEdition_Core', + 'Windows', + 'Linux', + 'macOS', + 'Dataverse', + 'PowerPlatform', + 'Dynamics365', + 'WebAPI', + 'OAuth' + ) # A URL to the license for this module. LicenseUri = 'https://github.com/rezanid/PSDataverse/blob/main/LICENSE' @@ -111,10 +121,10 @@ PrivateData = @{ ProjectUri = 'https://github.com/rezanid/PSDataverse' # A URL to an icon representing this module. - IconUri = 'https://github.com/rezanid/PSDataverse/raw/268e36c93ddfbcb6bcc2255beed9b03499210dfb/media/PSDataverse-Logo.png' + IconUri = 'https://raw.githubusercontent.com/rezanid/PSDataverse/main/media/PSDataverse-GalleryIcon.png' # ReleaseNotes of this module - ReleaseNotes = 'PSDataverse 2 release candidate. See https://github.com/rezanid/PSDataverse/blob/main/MIGRATION.md.' + ReleaseNotes = 'PSDataverse 2.0.0-rc.1 modernizes the module with PowerShell 7.6 and .NET 10, secure WAM/browser/device/IWA/application authentication, named connections, a bounded high-performance request engine, concurrent batch and multiple-operation APIs, convenient CRUD/metadata/import/export commands, structured errors, complete help, and cross-platform package verification. Migration guide: https://github.com/rezanid/PSDataverse/blob/main/MIGRATION.md. Full notes: https://github.com/rezanid/PSDataverse/releases/tag/v2.0.0-rc.1' # Prerelease string of this module Prerelease = 'rc.1' diff --git a/tests/PSDataverse.Module.Tests.ps1 b/tests/PSDataverse.Module.Tests.ps1 index 1b5e868..71926d2 100644 --- a/tests/PSDataverse.Module.Tests.ps1 +++ b/tests/PSDataverse.Module.Tests.ps1 @@ -52,6 +52,56 @@ Describe 'PSDataverse packaged module contract' { Should -Be (Split-Path (Resolve-Path $ModulePath).Path -Parent) } + It 'publishes complete PSDataverse 2 release-candidate metadata' { + $manifest = Test-ModuleManifest -Path $ModulePath + $metadata = $manifest.PrivateData.PSData + + $manifest.Author | Should -Be 'Reza Niroomand' + $manifest.CompanyName | Should -Be 'Reza Niroomand' + $manifest.Copyright | Should -Match 'Reza Niroomand' + $manifest.Description | Should -Match 'High-performance' + $manifest.Description | Should -Match 'Microsoft Dataverse' + $metadata.ProjectUri | Should -Be 'https://github.com/rezanid/PSDataverse' + $metadata.LicenseUri | Should -Match '^https://' + $metadata.IconUri | Should -Be ` + 'https://raw.githubusercontent.com/rezanid/PSDataverse/main/media/PSDataverse-GalleryIcon.png' + $metadata.ReleaseNotes | Should -Match '2\.0\.0-rc\.1' + $metadata.ReleaseNotes | Should -Match '/MIGRATION\.md' + $metadata.ReleaseNotes | Should -Match '/releases/tag/v2\.0\.0-rc\.1' + foreach ($tag in @( + 'PSEdition_Core', 'Windows', 'Linux', 'macOS', 'Dataverse', + 'PowerPlatform', 'Dynamics365', 'WebAPI', 'OAuth')) { + $metadata.Tags | Should -Contain $tag + } + } + + It 'keeps public release assets synchronized with the package version' { + $repositoryRoot = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..')) + $iconPath = Join-Path $repositoryRoot 'media/PSDataverse-GalleryIcon.png' + $notesPath = Join-Path $repositoryRoot 'docs/releases/2.0.0-rc.1.md' + $readmePath = Join-Path $repositoryRoot 'README.md' + + $iconPath | Should -Exist + $icon = [IO.File]::ReadAllBytes($iconPath) + [BitConverter]::ToString($icon[0..7]) | + Should -Be '89-50-4E-47-0D-0A-1A-0A' + $width = ($icon[16] -shl 24) -bor ($icon[17] -shl 16) -bor ` + ($icon[18] -shl 8) -bor $icon[19] + $height = ($icon[20] -shl 24) -bor ($icon[21] -shl 16) -bor ` + ($icon[22] -shl 8) -bor $icon[23] + $width | Should -Be 85 + $height | Should -Be 85 + + $notesPath | Should -Exist + (Get-Content -LiteralPath $notesPath -Raw) | + Should -Match 'PSDataverse 2\.0\.0-rc\.1' + $readme = Get-Content -LiteralPath $readmePath -Raw + $readme | Should -Match ` + 'Install-PSResource -Name PSDataverse -Version 2\.0\.0-rc\.1 -Prerelease' + $readme | Should -Match ` + 'Install-Module -Name PSDataverse -RequiredVersion 2\.0\.0-rc\.1 -AllowPrerelease' + } + It 'exports exactly the documented command surface' { $actual = @(Get-Command -Module PSDataverse | Sort-Object Name | Select-Object -ExpandProperty Name) $actual | Should -Be $expectedCommands