Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 81 additions & 3 deletions .github/workflows/build-and-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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) {
Expand All @@ -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
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -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
Expand Down
68 changes: 54 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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
```
Expand Down
6 changes: 5 additions & 1 deletion docs/PSDataverse-2-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
116 changes: 116 additions & 0 deletions docs/releases/2.0.0-rc.1.md
Original file line number Diff line number Diff line change
@@ -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).
Binary file added media/PSDataverse-GalleryIcon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
22 changes: 16 additions & 6 deletions src/Module/PSDataverse.psd1
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand All @@ -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'
Expand Down
Loading
Loading