diff --git a/.github/scripts/check-package.ps1 b/.github/scripts/check-package.ps1 new file mode 100644 index 0000000..437d917 --- /dev/null +++ b/.github/scripts/check-package.ps1 @@ -0,0 +1,136 @@ +#Requires -Version 7.0 +<# +.SYNOPSIS + Checks the PDFStream.NET NuGet package before it is kept as a CI artifact or published to nuget.org. + +.DESCRIPTION + Both workflows run this one script: .github/workflows/ci.yml on every push and pull request, and + .github/workflows/publish.yml right before it pushes to nuget.org. A package can therefore only be published + if it passes exactly the checks CI runs. + + It fails (exit code 1, with one "::error" line per problem, which GitHub Actions shows as annotations) when the + package: + - is not exactly one PDFStream.NET..nupkg in the folder; + - lacks the licence, the third-party notices, the package readme, the icon or either library assembly; + - has the wrong id, title, version, licence, readme, icon, authors or repository in its nuspec, no + release notes, or no PDFium dependency at the tested version; + - carries the repository README instead of the package readme (raw HTML, a link or image that is not + absolute https, or an install command for another version); + - carries an icon that is not a square PNG of at least 128 px and at most 1 MB (nuget.org's limit); + - picked up a file type that has no business in it (keys, certificates, settings, scripts). + + Run it locally from the repository root after "dotnet pack ... --output ": + + pwsh -File .github/scripts/check-package.ps1 -PackageFolder +#> +[CmdletBinding()] +param( + # The folder dotnet pack wrote the package into. + [string] $PackageFolder = 'artifacts/package' +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +Add-Type -AssemblyName System.IO.Compression.FileSystem + +# The version being released: VersionPrefix plus VersionSuffix in Directory.Build.props. A version published on +# nuget.org is permanent, so the check pins it exactly. Change it together with that file when a new version is +# released; this is the only copy of the pin. +$expectedVersion = '1.0.0-rc.2' +$expectedId = 'PDFStream.NET' +$expectedRepository = 'https://github.com/P4Software/PDFStream.NET' + +# The package id, the assembly and the namespace are all PDFStream.NET, so the file is +# PDFStream.NET..nupkg and its manifest PDFStream.NET.nuspec. Exactly one must exist. +$packages = @(Get-ChildItem -Path $PackageFolder -Filter "$expectedId.*.nupkg" | Where-Object { $_.Name -notlike '*.snupkg' }) +if ($packages.Count -ne 1) { throw "Expected one $expectedId.$expectedVersion.nupkg in '$PackageFolder', found $($packages.Count): $($packages.Name -join ', ')" } +if ($packages[0].Name -cne "$expectedId.$expectedVersion.nupkg") { throw "The package file is '$($packages[0].Name)', not $expectedId.$expectedVersion.nupkg" } +$package = $packages[0] + +# Reads one entry of the package as text, or as bytes; $null when the entry is missing. +function Read-EntryText($zip, [string] $name) { + $entry = $zip.Entries | Where-Object { $_.FullName -ceq $name } + if (-not $entry) { return $null } + $reader = [IO.StreamReader]::new($entry.Open()) + try { return $reader.ReadToEnd() } finally { $reader.Dispose() } +} +function Read-EntryBytes($zip, [string] $name) { + $entry = $zip.Entries | Where-Object { $_.FullName -ceq $name } + if (-not $entry) { return $null } + $stream = $entry.Open(); $memory = [IO.MemoryStream]::new() + try { $stream.CopyTo($memory); return , $memory.ToArray() } finally { $stream.Dispose(); $memory.Dispose() } +} + +$zip = [IO.Compression.ZipFile]::OpenRead($package.FullName) +try { + $entries = @($zip.Entries | ForEach-Object { $_.FullName }) + $nuspecText = Read-EntryText $zip "$expectedId.nuspec" + if ($null -eq $nuspecText) { throw "The package has no $expectedId.nuspec." } + [xml] $nuspec = $nuspecText + $readme = Read-EntryText $zip 'README.md' + $icon = Read-EntryBytes $zip 'icon.png' +} finally { $zip.Dispose() } + +$problems = @() +foreach ($required in 'LICENSE', 'THIRD-PARTY-NOTICES.md', 'README.md', 'icon.png', "lib/net8.0-windows7.0/$expectedId.dll", "lib/net10.0-windows7.0/$expectedId.dll") { + if ($entries -cnotcontains $required) { $problems += "missing file: $required" } +} + +# The nuspec metadata nuget.org shows on the package page. +$metadata = $nuspec.package.metadata +# Reads an optional nuspec element as text: missing elements give an empty string instead of a strict-mode error. +function Get-MetadataText([string] $name) { + $node = $metadata.SelectSingleNode("*[local-name()='$name']") + if ($null -eq $node) { return '' } + return $node.InnerText +} +if ((Get-MetadataText 'id') -cne $expectedId) { $problems += "the package id is '$(Get-MetadataText 'id')', not $expectedId" } +if ((Get-MetadataText 'title') -cne $expectedId) { $problems += "the package title is '$(Get-MetadataText 'title')', not $expectedId" } +if ((Get-MetadataText 'version') -cne $expectedVersion) { $problems += "the package version is '$(Get-MetadataText 'version')', not $expectedVersion" } +if ((Get-MetadataText 'license') -ne 'MIT') { $problems += 'the licence expression is not MIT' } +if ((Get-MetadataText 'readme') -cne 'README.md') { $problems += 'the package readme is not README.md' } +if ((Get-MetadataText 'icon') -cne 'icon.png') { $problems += 'the nuspec has no icon.png' } +if ((Get-MetadataText 'authors') -ne 'P4 Software') { $problems += 'the authors are not P4 Software' } +if ([string]::IsNullOrWhiteSpace((Get-MetadataText 'releaseNotes'))) { $problems += 'the package has no release notes' } +$repository = $metadata.SelectSingleNode("*[local-name()='repository']") +if ($null -eq $repository -or $repository.GetAttribute('url') -cne $expectedRepository) { $problems += 'the repository URL is missing or wrong' } +$groups = @($metadata.SelectNodes("*[local-name()='dependencies']/*[local-name()='group']")) +if ($groups.Count -eq 0) { $problems += 'the package has no dependency groups' } +foreach ($group in $groups) { + $pdfium = @($group.SelectNodes("*[local-name()='dependency'][@id='bblanchon.PDFium.Win32']")) + if ($pdfium.Count -ne 1) { $problems += "$($group.GetAttribute('targetFramework')) does not depend on bblanchon.PDFium.Win32 (pdfium.dll)" } + # The exact PDFium build that was tested (the nuspec writes it as "160.0.8165", which NuGet reads as "160.0.8165 or newer"). + elseif ($pdfium[0].GetAttribute('version') -cne '160.0.8165') { $problems += "$($group.GetAttribute('targetFramework')) depends on bblanchon.PDFium.Win32 $($pdfium[0].GetAttribute('version')), not 160.0.8165" } +} + +# The package readme must be the one written for nuget.org (src/PDFStream.NET/README.nuget.md), not the GitHub +# README: nuget.org strips raw HTML, cannot follow relative links and shows images only over https from hosts it +# trusts. Its install command must name the version being released. +if ($null -ne $readme) { + if ($readme -match '(?i)<\s*/?\s*(div|p|img|br|a|table|span|picture|source|details|summary|h[1-6])\b') { $problems += 'README.md in the package contains raw HTML; it must be the package readme (README.nuget.md)' } + $targets = @([regex]::Matches($readme, '\]\(\s*([^)\s]+)') | ForEach-Object { $_.Groups[1].Value }) + $notHttps = @($targets | Where-Object { $_ -notmatch '^https://' }) + if ($notHttps.Count -gt 0) { $problems += "README.md in the package has links or images that are not absolute https: $($notHttps -join ', ')" } + if (-not $readme.Contains("dotnet add package $expectedId --version $expectedVersion")) { $problems += "README.md in the package does not show 'dotnet add package $expectedId --version $expectedVersion'" } +} + +# The icon: a PNG (signature check), square, at least 128 px (nuget.org recommends 128 x 128), at most 1 MB. +if ($null -ne $icon) { + $pngSignature = [byte[]] (0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A) + if ($icon.Length -lt 24 -or -not [Linq.Enumerable]::SequenceEqual([byte[]] $icon[0..7], $pngSignature)) { $problems += 'icon.png is not a PNG file' } + else { + # Width and height are the big-endian 32-bit numbers at bytes 16 and 20 (the IHDR chunk). + $width = ([int] $icon[16] -shl 24) -bor ([int] $icon[17] -shl 16) -bor ([int] $icon[18] -shl 8) -bor [int] $icon[19] + $height = ([int] $icon[20] -shl 24) -bor ([int] $icon[21] -shl 16) -bor ([int] $icon[22] -shl 8) -bor [int] $icon[23] + if ($width -ne $height -or $width -lt 128) { $problems += "icon.png is $width x $height; it must be square and at least 128 px" } + } + if ($icon.Length -gt 1MB) { $problems += "icon.png is $($icon.Length) bytes; nuget.org accepts at most 1 MB" } +} + +$unexpected = @($entries | Where-Object { $_ -match '\.(snk|pfx|p12|pem|key|cer|ps1|cmd|bat|json|config)$' }) +if ($unexpected.Count -gt 0) { $problems += "unexpected files: $($unexpected -join ', ')" } + +"Package: $($package.Name)"; $entries | Sort-Object | ForEach-Object { " $_" } +if ($problems.Count -gt 0) { $problems | ForEach-Object { "::error title=Package check::$_" }; exit 1 } +"The $expectedId package has the licence, the third-party notices, the package readme, the icon, the metadata and the PDFium dependency." +exit 0 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6355831..bd9c25a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -140,53 +140,12 @@ jobs: - name: Pack the NuGet package run: dotnet pack src/PDFStream.NET/PDFStream.NET.csproj --configuration Release --no-build --output artifacts/package - # Fails the run if the package lost its licence, notices, readme, metadata or PDFium dependency, or - # picked up a file type that has no business in it (keys, certificates, settings, scripts). + # Fails the run if the package lost its licence, notices, package readme, icon, metadata or PDFium dependency, + # carries the wrong version or readme, or picked up a file type that has no business in it (keys, + # certificates, settings, scripts). The checks live in one script that the publish workflow runs as well, + # so a package can only be published if it passes exactly these checks. - name: Check the package contents - run: | - Add-Type -AssemblyName System.IO.Compression.FileSystem - # The version being released: VersionPrefix plus VersionSuffix in Directory.Build.props. A version published - # on nuget.org is permanent, so the check pins it exactly. Change it together with that file when a new - # version is released. - $expectedVersion = '1.0.0-rc.1' - # The package id, the assembly and the namespace are all PDFStream.NET, so the file is - # PDFStream.NET..nupkg and its manifest PDFStream.NET.nuspec. Exactly one must exist. - $packages = @(Get-ChildItem artifacts/package -Filter 'PDFStream.NET.*.nupkg' | Where-Object { $_.Name -notlike '*.snupkg' }) - if ($packages.Count -ne 1) { throw "Expected one PDFStream.NET.$expectedVersion.nupkg, found $($packages.Count): $($packages.Name -join ', ')" } - if ($packages[0].Name -cne "PDFStream.NET.$expectedVersion.nupkg") { throw "The package file is '$($packages[0].Name)', not PDFStream.NET.$expectedVersion.nupkg" } - $package = $packages[0] - $zip = [IO.Compression.ZipFile]::OpenRead($package.FullName) - try { - $entries = @($zip.Entries | ForEach-Object { $_.FullName }) - $manifest = $zip.Entries | Where-Object { $_.FullName -ceq 'PDFStream.NET.nuspec' } - if (-not $manifest) { throw 'The package has no PDFStream.NET.nuspec.' } - $reader = [IO.StreamReader]::new($manifest.Open()) - [xml]$nuspec = $reader.ReadToEnd() - $reader.Dispose() - } finally { $zip.Dispose() } - $problems = @() - foreach ($required in 'LICENSE', 'THIRD-PARTY-NOTICES.md', 'README.md', 'lib/net8.0-windows7.0/PDFStream.NET.dll', 'lib/net10.0-windows7.0/PDFStream.NET.dll') { - if ($entries -cnotcontains $required) { $problems += "missing file: $required" } - } - $metadata = $nuspec.package.metadata - if ($metadata.id -cne 'PDFStream.NET') { $problems += "the package id is '$($metadata.id)', not PDFStream.NET" } - if ($metadata.title -cne 'PDFStream.NET') { $problems += "the package title is '$($metadata.title)', not PDFStream.NET" } - if ($metadata.version -cne $expectedVersion) { $problems += "the package version is '$($metadata.version)', not $expectedVersion" } - if ($metadata.license.'#text' -ne 'MIT') { $problems += 'the licence expression is not MIT' } - if ($metadata.readme -ne 'README.md') { $problems += 'the package readme is not README.md' } - if ($metadata.authors -ne 'P4 Software') { $problems += 'the authors are not P4 Software' } - if ($metadata.repository.url -cne 'https://github.com/P4Software/PDFStream.NET') { $problems += 'the repository URL is missing or wrong' } - foreach ($group in @($metadata.dependencies.group)) { - $pdfium = @($group.dependency | Where-Object { $_.id -ceq 'bblanchon.PDFium.Win32' }) - if ($pdfium.Count -ne 1) { $problems += "$($group.targetFramework) does not depend on bblanchon.PDFium.Win32 (pdfium.dll)" } - # The exact PDFium build that was tested (the nuspec writes it as "160.0.8165", which NuGet reads as "160.0.8165 or newer"). - elseif ($pdfium[0].version -cne '160.0.8165') { $problems += "$($group.targetFramework) depends on bblanchon.PDFium.Win32 $($pdfium[0].version), not 160.0.8165" } - } - $unexpected = @($entries | Where-Object { $_ -match '\.(snk|pfx|p12|pem|key|cer|ps1|cmd|bat|json|config)$' }) - if ($unexpected.Count -gt 0) { $problems += "unexpected files: $($unexpected -join ', ')" } - "Package: $($package.Name)"; $entries | Sort-Object | ForEach-Object { " $_" } - if ($problems.Count -gt 0) { $problems | ForEach-Object { "::error title=Package check::$_" }; exit 1 } - 'The PDFStream.NET package has the licence, the third-party notices, the readme, the metadata and the PDFium dependency.' + run: ./.github/scripts/check-package.ps1 -PackageFolder artifacts/package - name: Upload the NuGet package uses: actions/upload-artifact@v7 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..fa0af44 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,212 @@ +# Publishes PDFStream.NET to nuget.org with NuGet Trusted Publishing: no long-lived API key exists anywhere. +# +# How it works: the job asks GitHub for a short-lived OIDC token (that is what "id-token: write" allows), the +# NuGet/login action exchanges it at nuget.org for an API key that is valid for one hour, and the push uses that +# key right away. nuget.org only hands out the key when the token matches a Trusted Publishing policy that names +# this repository owner, this repository, this workflow file (publish.yml: renaming the file breaks the policy) +# and the "release" environment. See "Releasing" in CONTRIBUTING.md for the one-time set-up and the steps of +# each release, and https://learn.microsoft.com/nuget/nuget-org/trusted-publishing for the mechanism. +# +# Safety: +# - It only runs when someone starts it by hand (Actions tab, "Run workflow"); never on push or pull request. +# - It refuses to run from any branch other than main, before anything is built or approved. +# - The publish job runs in the "release" environment, which the owner protects with a required reviewer, so +# nothing is pushed without an approval click. +# - It builds, tests, packs and checks the package exactly as CI does (the same package-check script), and +# pushes only a package that passed. +# - The nuget.org user name comes from the repository secret NUGET_USER; the API key is masked by the login +# action and only ever passed through an environment variable, never echoed. +# - --skip-duplicate makes a re-run harmless: a version that is already on nuget.org is left alone. +# +# Third-party actions are pinned to full commit SHAs (the release each SHA belongs to is in the comment), so a +# moved tag cannot change what runs with the permission to publish. +name: Publish to NuGet + +on: + workflow_dispatch: + +# Nothing is granted workflow-wide; the publish job asks for exactly what it needs. +permissions: {} + +# Two publishes must never overlap. A second run waits for the first instead of cancelling it. +concurrency: + group: publish-to-nuget + cancel-in-progress: false + +env: + # No usage data leaves the build: the .NET CLI and Microsoft Testing Platform both honour these. + DOTNET_CLI_TELEMETRY_OPTOUT: '1' + TESTINGPLATFORM_TELEMETRY_OPTOUT: '1' + DOTNET_NOLOGO: '1' + +jobs: + # Fails fast, with a plain message, when the run was started on another branch, so nobody is asked to approve a + # release that can only be refused afterwards. + check-branch: + name: Check that the run is on main + runs-on: windows-latest + timeout-minutes: 5 + permissions: {} + steps: + - name: Refuse to publish from any branch other than main + shell: pwsh + env: + RUN_REF: ${{ github.ref }} + run: | + if ($env:RUN_REF -cne 'refs/heads/main') { + "::error title=Not on main::This workflow publishes to nuget.org only from the main branch, but it was started on '$env:RUN_REF'. Nothing was built or published. Start it again from the Actions tab and choose 'Branch: main' under 'Use workflow from'." + exit 1 + } + 'The run is on main: the publish job can start once it is approved.' + + publish: + name: Build, test, check and publish (windows-latest) + needs: check-branch + # A second guard on the job itself, in case the first job is ever removed or skipped. + if: github.ref == 'refs/heads/main' + runs-on: windows-latest + timeout-minutes: 30 + # The owner protects this environment with a required reviewer; the nuget.org policy names it too. + environment: release + permissions: + contents: read # check out the repository + id-token: write # ask GitHub for the OIDC token that nuget.org exchanges for a short-lived API key + defaults: + run: + shell: pwsh + + steps: + # Fails before anything is built when the one setting this workflow needs is missing. The value is never + # printed. + - name: Check that the NUGET_USER secret is set + env: + NUGET_USER: ${{ secrets.NUGET_USER }} + run: | + if ([string]::IsNullOrWhiteSpace($env:NUGET_USER)) { + "::error title=NUGET_USER missing::The repository secret NUGET_USER is not set. Add it under Settings > Secrets and variables > Actions, with the nuget.org profile name (not an e-mail address) as its value, then run this workflow again. Nothing was published." + exit 1 + } + 'The NUGET_USER secret is set.' + + - name: Check out the repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Install the .NET SDKs + uses: actions/setup-dotnet@0f4a354dd5547a28c70b7853dbd95d5b67886e73 # v6.1.0 + with: + # The same SDKs as ci.yml: the .NET 10 SDK builds both targets and runs the tests through Microsoft + # Testing Platform; the .NET 8 install brings the runtime the net8.0-windows tests run on. + dotnet-version: | + 8.0.x + 10.0.x + + - name: Show the .NET SDK in use + run: dotnet --version + + - name: Restore + run: dotnet restore + + # Warnings are errors here: a release is built from a tree with no warnings at all. + - name: Build (warnings as errors) + run: dotnet build --configuration Release --no-restore -warnaserror + + - name: Test (net8.0-windows) + run: >- + dotnet test --project tests/PDFStream.NET.Tests/PDFStream.NET.Tests.csproj + --framework net8.0-windows --configuration Release --no-build + --results-directory artifacts/test-results + --report-xunit-trx --report-xunit-trx-filename net8.0-windows.trx + + - name: Test (net10.0-windows) + run: >- + dotnet test --project tests/PDFStream.NET.Tests/PDFStream.NET.Tests.csproj + --framework net10.0-windows --configuration Release --no-build + --results-directory artifacts/test-results + --report-xunit-trx --report-xunit-trx-filename net10.0-windows.trx + + - name: Upload the test results + if: always() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: publish-test-results + path: artifacts/test-results + if-no-files-found: warn + + - name: Pack the NuGet package + run: dotnet pack src/PDFStream.NET/PDFStream.NET.csproj --configuration Release --no-build --output artifacts/package + + # The same script ci.yml runs. It fails unless the folder holds exactly PDFStream.NET..nupkg + # with the id PDFStream.NET, the icon, the package readme, the licence, the notices and the right metadata. + - name: Check the package contents + run: ./.github/scripts/check-package.ps1 -PackageFolder artifacts/package + + # The file name and the version for the steps below. The check above has already proved that there is + # exactly one package and that its version is the pinned one. + - name: Find the package + id: package + run: | + $nupkg = Get-ChildItem artifacts/package -Filter 'PDFStream.NET.*.nupkg' | Where-Object { $_.Name -notlike '*.snupkg' } | Select-Object -First 1 + $version = $nupkg.BaseName.Substring('PDFStream.NET.'.Length) + "path=$($nupkg.FullName)" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8 + "version=$version" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8 + "Package to publish: $($nupkg.Name) (version $version)" + + - name: Upload the NuGet package + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: PDFStream.NET-${{ steps.package.outputs.version }}-nuget-package + path: artifacts/package + if-no-files-found: error + + # Requested only now, right before the push, because the key it returns is valid for one hour. + - name: Get a short-lived nuget.org API key (Trusted Publishing) + id: login + uses: NuGet/login@8d196754b4036150537f80ac539e15c2f1028841 # v1.2.0 + with: + user: ${{ secrets.NUGET_USER }} + + - name: Push the package to nuget.org + id: push + env: + NUGET_API_KEY: ${{ steps.login.outputs.NUGET_API_KEY }} + PACKAGE_PATH: ${{ steps.package.outputs.path }} + run: | + $output = dotnet nuget push $env:PACKAGE_PATH --api-key $env:NUGET_API_KEY --source https://api.nuget.org/v3/index.json --skip-duplicate 2>&1 + $exitCode = $LASTEXITCODE + $output | ForEach-Object { "$_" } + if ($exitCode -ne 0) { + "::error title=Push failed::dotnet nuget push failed with exit code $exitCode. Read the lines above; nothing was published by this run." + exit $exitCode + } + # With --skip-duplicate an existing version is reported as a conflict and skipped, not as a failure. + $skipped = [bool] ($output | Select-String -SimpleMatch 'already exists') + "skipped=$($skipped.ToString().ToLowerInvariant())" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8 + + - name: Summary + env: + PACKAGE_VERSION: ${{ steps.package.outputs.version }} + SKIPPED: ${{ steps.push.outputs.skipped }} + run: | + $url = "https://www.nuget.org/packages/PDFStream.NET/$env:PACKAGE_VERSION" + if ($env:SKIPPED -eq 'true') { + $lines = @( + '### PDFStream.NET was already on nuget.org', + '', + "Version $env:PACKAGE_VERSION of PDFStream.NET already exists on nuget.org, so nothing was pushed (a version can never be replaced).", + "To release a change, raise the version and run this workflow again. Package page: $url" + ) + } else { + $lines = @( + '### PDFStream.NET pushed to nuget.org', + '', + "- Package: PDFStream.NET", + "- Version: $env:PACKAGE_VERSION", + "- Page: $url", + '', + 'nuget.org now validates and indexes the package. For some minutes the page shows the version as Validating, and it cannot be installed yet; that is normal. A prerelease is listed only when "Include prerelease" is ticked.' + ) + } + $lines | ForEach-Object { $_ } + $lines | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8 diff --git a/CHANGELOG.md b/CHANGELOG.md index 3176ef8..7e8c93c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,74 @@ All notable changes to PDFStream.NET are recorded here. The format follows ## [Unreleased] +## 1.0.0-rc.2 - 2026-11-21 + +A package-page release. A version on nuget.org can never be edited, so the new nuget.org page ships as a new +version. There is no library code change: the assemblies are built from the same code as 1.0.0-rc.1, and the +manual release checklist rows are as open as they were for 1.0.0-rc.1. + +### Added + +- A package icon, `src/PDFStream.NET/icon.png` (256 x 256, flat P4 Software brand colours): a PDF page with a + folded orange corner whose downward "stream" chevrons lead into a printer, with the printed sheet coming out. + It is drawn by `tools/make-icon.ps1` (PowerShell 7 and System.Drawing, no other tools), so it can be rebuilt + and reviewed like code; running the script twice gives the same file. +- A package readme written for nuget.org, `src/PDFStream.NET/README.nuget.md`, packed as `README.md`: a one-line + pitch, badges, why, features, a quick start, a stream, page range and duplex example, install, requirements, a + status box with what is and is not verified, security and limits, and links. It uses no HTML, only absolute + https links, and images only from shields.io. The repository `README.md` stays the GitHub page and is no longer + packed. +- `.github/scripts/check-package.ps1`: the package check, moved out of `ci.yml` into one script, the only place + that pins the version being released. +- `.github/workflows/publish.yml` ("Publish to NuGet"): publishes to nuget.org with NuGet Trusted Publishing, so + no API key is stored. It runs only when started by hand, only from `main`, in the `release` environment (which + needs an approval); it builds with warnings as errors, runs both test suites, packs, runs the same package + check as CI, uploads the package, then asks nuget.org for a one-hour key and pushes with `--skip-duplicate`. + `CONTRIBUTING.md` describes the one-time set-up and the steps of each release. It has not run yet: the + nuget.org policy, the environment and the secret it needs do not exist yet. + +### Changed + +- Package metadata: a benefit-led description, search tags (`pdf print printing printer silent windows pdfium + batch automation server service pdf-printing`), release notes with a link to this changelog, and the icon. +- The package check now also fails without `icon.png` at the package root or `icon.png` in the + nuspec, for an icon that is not a square PNG of at least 128 px and at most 1 MB, without release notes, and + when `README.md` in the package is not the package readme (raw HTML, a link or image that is not absolute + https, or no install command for the version being released). It expects version 1.0.0-rc.2. +- `README.md`, `SECURITY.md` and `CONTRIBUTING.md` no longer say the package is unpublished: 1.0.0-rc.1 was + published on nuget.org on 2026-11-21. `README.md` has a NuGet badge, and `CONTRIBUTING.md` says where the + package readme, the icon and the version pin live. `docs/usage.md` adds `--prerelease` to its install line. +- `docs/release-checklist.md` records that 1.0.0-rc.1 was published with the manual rows still Not run, and one + reported (not signed-off) print through an installed print service. + +### Verified + +On one Windows 11 x64 machine, .NET SDK 11.0.100, on 2026-11-21: + +- `dotnet build -warnaserror` from the repository root: 0 warnings, 0 errors, on `net8.0-windows` and + `net10.0-windows`. +- The full test suite in a 64-bit process: `net8.0-windows` 452 passed and `net10.0-windows` 477 passed, none + skipped (Debug). The 32-bit runs were not repeated for this version, which has no library code change. +- `dotnet pack -c Release` into a folder outside the repository gave `PDFStream.NET.1.0.0-rc.2.nupkg` with + `icon.png`, `README.md` (byte for byte `README.nuget.md`), `LICENSE`, `THIRD-PARTY-NOTICES.md` and + `lib/net8.0-windows7.0/PDFStream.NET.dll` and `lib/net10.0-windows7.0/PDFStream.NET.dll`; the nuspec has the + icon, the readme, the tags and the release notes. The package check passed against it, and failed, as it must, + against copies without `icon.png`, without ``, without `README.md` and with the GitHub README in its place. +- The two C# samples in `README.nuget.md`, compiled unchanged as console programs against the library for both + frameworks with warnings as errors: 0 warnings, 0 errors. +- A separate win-x64 app on `net10.0-windows` restored the package (``) from that folder into an empty package cache and printed a one-page PDF to + *Microsoft Print to PDF* with `OutputFile` (status Ok, one page sent, a one-page PDF written), and the + `pdfium.dll` next to its exe was the x64 one from the PDFium package (same SHA-256). +- `README.nuget.md` rendered through GitHub's markdown API: one table, two block quotes, all links and images + absolute https. nuget.org renders with its own engine, which was not seen before publishing. +- The published 1.0.0-rc.1 package names commit `e8cf1df` in its nuspec, the commit this version branches from: + `git diff e8cf1df -- '*.cs'` is empty, and both versions have the same dependency groups (System.Drawing.Common + 8.0.34 and 10.0.15, bblanchon.PDFium.Win32 160.0.8165). +- Against nuget.org: a plain `dotnet add package PDFStream.NET` stops with "There are no stable versions + available, 1.0.0-rc.1 is the best available. Consider adding the --prerelease option", and + `dotnet add package PDFStream.NET --prerelease` adds 1.0.0-rc.1. + ## 1.0.0-rc.1 - 2026-11-21 The first release of PDFStream.NET, a release candidate (a prerelease on NuGet). The stable 1.0.0 follows once the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29e9c73..14f750c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,9 +77,20 @@ dotnet publish samples/PDFStream.NET.TestPrint/PDFStream.NET.TestPrint.csproj -- ``` The package is named `PDFStream.NET`, so `dotnet pack` writes `artifacts/package/PDFStream.NET..nupkg` -(`PDFStream.NET.1.0.0-rc.1.nupkg` for the first release). The version is set in one place, `VersionPrefix` and -`VersionSuffix` in `Directory.Build.props`, and the package check in `.github/workflows/ci.yml` expects the same -version: change both together when a new version is released. +(`PDFStream.NET.1.0.0-rc.2.nupkg` for the current version). The version is set in one place, `VersionPrefix` and +`VersionSuffix` in `Directory.Build.props`, and the package check, `.github/scripts/check-package.ps1`, expects the +same version: change both together when a new version is released. Run the check locally after a pack: + +```text +pwsh -File .github/scripts/check-package.ps1 -PackageFolder artifacts/package +``` + +The package page on nuget.org is `src/PDFStream.NET/README.nuget.md`, packed as `README.md`; the repository's own +`README.md` is the GitHub page and is not packed. Write the package readme for nuget.org: no HTML, only absolute +`https` links, and images only from hosts nuget.org allows (for example `img.shields.io`). Its +`dotnet add package PDFStream.NET --version ` line must name the version being released; the package check +fails otherwise. The package icon, `src/PDFStream.NET/icon.png`, is drawn by `tools/make-icon.ps1` +(`pwsh -File tools/make-icon.ps1`): change the script and run it again rather than editing the picture. The assembly inside it is `PDFStream.NET.dll` and the namespace is `PDFStream.NET`. The package does not contain `pdfium.dll` itself: it depends on the `bblanchon.PDFium.Win32` package, whose @@ -90,7 +101,7 @@ with ``, add folder (so an older copy of the package in your cache cannot stand in for the new one), build and publish it with `-r win-x64`, `-r win-x86`, `-r win-arm64` and with no runtime identifier, for `net8.0-windows` and `net10.0-windows`, and check that the `pdfium.dll` next to the exe is the one for that architecture. CI checks -the package's own contents (licence, notices, readme, metadata, the PDFium dependency) on every run. +the package's own contents (licence, notices, package readme, icon, metadata, the PDFium dependency) on every run. The publish command makes one exe that includes .NET and `pdfium.dll`, so it runs by double-click on a machine without .NET. @@ -101,6 +112,39 @@ Work through the [manual release checklist](docs/release-checklist.md). Nothing someone has run the check and written the machine, the date and the result in the row. Never mark a row from memory. +## Releasing + +Releases are published to nuget.org by the **Publish to NuGet** workflow (`.github/workflows/publish.yml`) with +NuGet Trusted Publishing: GitHub gives the workflow a short-lived token, nuget.org exchanges it for an API key that +is valid for one hour, and the workflow pushes with it. No API key is stored anywhere, so there is none to rotate +or leak. The workflow runs only when started by hand, only from `main`, and only after a reviewer approves it. + +One-time set-up (the owner): + +1. On nuget.org, open your name menu, choose **Trusted Publishing** and add a policy: Repository Owner + `P4Software`, Repository `PDFStream.NET`, Workflow File `publish.yml` (the file name only), Environment + `release`, with the scope to push new versions of the package `PDFStream.NET`. +2. On GitHub, in the repository settings, create the environment `release` with a required reviewer. +3. Add the repository secret `NUGET_USER` with the nuget.org profile name (not an e-mail address) as its value. + +If nuget.org shows the new policy as temporarily active (it does this when it cannot yet look up the repository's +IDs, usually for private repositories), it stays active for 7 days and becomes permanently active with the first +successful publish. + +Each release: + +1. Set the version: `VersionPrefix` and `VersionSuffix` in `Directory.Build.props`, the pinned version in + `.github/scripts/check-package.ps1`, and the `--version` install line in `src/PDFStream.NET/README.nuget.md`. + Add the version's section to `CHANGELOG.md` and update `PackageReleaseNotes` in the library's project file. +2. Merge to `main` once CI is green. +3. On GitHub, open **Actions**, choose **Publish to NuGet**, then **Run workflow** with `main` selected. +4. Approve the run when GitHub asks (the `release` environment). The workflow builds with warnings as errors, + runs both test suites, packs, runs the package check and only then pushes. +5. Wait while nuget.org shows the new version as **Validating**; it can be installed once that is done, usually + within some minutes. A version on nuget.org can never be changed or reused: a mistake means a new version. + +Re-running the workflow for a version that is already on nuget.org pushes nothing (`--skip-duplicate`). + ## Rules for code - The public API never throws for bad input or printer problems: it returns a `PrintResult` with a status and diff --git a/Directory.Build.props b/Directory.Build.props index dbf485b..73796ba 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -37,20 +37,22 @@ Copyright (c) 2026 P4 Software MIT 1.0.0 - rc.1 + rc.2 diff --git a/README.md b/README.md index c9ab859..544e3d2 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ **Free, open-source PDF printing for .NET.** Send a PDF to any Windows printer in one line of code. No Adobe Reader, no licence keys, no watermarks. -![Status: 1.0.0-rc.1 release candidate](https://img.shields.io/badge/status-1.0.0--rc.1%20release%20candidate-yellow) +[![NuGet](https://img.shields.io/nuget/vpre/PDFStream.NET?label=NuGet)](https://www.nuget.org/packages/PDFStream.NET) ![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078D4) ![.NET 8 and 10](https://img.shields.io/badge/.NET-8%20%7C%2010-512BD4) ![Licence: MIT](https://img.shields.io/badge/licence-MIT-brightgreen) @@ -14,12 +14,14 @@ Send a PDF to any Windows printer in one line of code. No Adobe Reader, no licen --- -> **Status: version 1.0.0-rc.1, the first release (a release candidate).** The library is complete and its automated tests pass, including -> real prints to *Microsoft Print to PDF* in 64-bit and 32-bit processes. The manual release checklist -> (physical printers, a Windows service, a scheduled task, Arm64 hardware) is **not complete yet**, and the -> package (`PDFStream.NET`) is **not on NuGet yet**. The stable 1.0.0 follows once the remaining checklist rows -> (Arm64, a scheduled task, IIS, other physical and duplex printers) are verified. PDF to image conversion is -> planned after 1.0. +> **Status: a release candidate, on NuGet as a prerelease.** Version 1.0.0-rc.1, the first release, was +> published on [nuget.org](https://www.nuget.org/packages/PDFStream.NET) on 2026-11-21; 1.0.0-rc.2 is the version +> with the new package page (icon, package readme, description, tags), with no library code change. The library is +> complete and its automated tests pass, including real prints to *Microsoft Print to PDF* in 64-bit and 32-bit +> processes. The manual release checklist (physical printers, a Windows service, a scheduled task, Arm64 +> hardware) is **not complete yet**. The stable 1.0.0 follows once the remaining checklist rows (Arm64, a +> scheduled task, IIS, other physical and duplex printers) are verified. PDF to image conversion is planned after +> 1.0. > See [what has been verified](#what-has-been-verified). ## Why PDFStream.NET? @@ -49,22 +51,21 @@ own warehouse software, and we are sharing it so nobody else has to pay for it. ## Install -PDFStream.NET is not published on NuGet yet. Version 1.0.0-rc.1 is the first release and a prerelease, so once it -is published a plain `dotnet add package PDFStream.NET` finds nothing until the stable 1.0.0 exists. Add the -prerelease explicitly: +PDFStream.NET is on [nuget.org](https://www.nuget.org/packages/PDFStream.NET) as a prerelease: 1.0.0-rc.1 was +published on 2026-11-21, and 1.0.0-rc.2 is the version with the new package page. Until the stable 1.0.0 exists, a +plain `dotnet add package PDFStream.NET` finds no stable version, so add the prerelease explicitly: ```text dotnet add package PDFStream.NET --prerelease ``` -or name the version: `dotnet add package PDFStream.NET --version 1.0.0-rc.1`. On nuget.org the package page lists -prereleases only when "Include prerelease" is ticked. +or name the version: `dotnet add package PDFStream.NET --version 1.0.0-rc.2`. In the Visual Studio package manager, +tick "Include prerelease" to see it. The package, the assembly and the namespace are all called `PDFStream.NET`: in your code you write `using PDFStream.NET;`. -Until then, build the package from this repository (see [CONTRIBUTING.md](https://github.com/P4Software/PDFStream.NET/blob/main/CONTRIBUTING.md)) and add the -folder it lands in as a package source. +To build the package yourself from this repository, see [CONTRIBUTING.md](https://github.com/P4Software/PDFStream.NET/blob/main/CONTRIBUTING.md). Requirements: @@ -162,10 +163,16 @@ On one Windows 11 x64 machine: 2026-11-21: the package was packed as `PDFStream.NET.1.0.0-rc.1.nupkg` and used from a separate win-x64 app on `net10.0-windows` with `using PDFStream.NET;`, which printed a PDF to *Microsoft Print to PDF*, and the right `pdfium.dll` landed next to the exe. +- Version 1.0.0-rc.2 (the package page; the library code is unchanged), on 2026-11-21, in a 64-bit process only: + the full test suite passed on both frameworks (452 on `net8.0-windows`, 477 on `net10.0-windows`, none + skipped); `PDFStream.NET.1.0.0-rc.2.nupkg` passed the package check with the icon and the package readme + inside; and a separate win-x64 app on `net10.0-windows` restored it into an empty package cache and printed a + one-page PDF to *Microsoft Print to PDF* with `OutputFile` (status Ok, one page in the output file). Not verified yet (they are on the [release checklist](https://github.com/P4Software/PDFStream.NET/blob/main/docs/release-checklist.md)): running on an Arm64 PC, physical printers (duplex, network printers), and printing from a Windows service, a scheduled task -or IIS. +or IIS. One real print through an installed print service on one PC has been reported as working; that is a +single report, so the checklist row for Windows services stays open. ## Roadmap @@ -175,8 +182,9 @@ or IIS. | 2 | Silent printing of a PDF to a chosen printer | Done | | 3 | Print options (ranges, copies, duplex, colour, scaling, paper source, print to file) | Done | | 4 | Password-protected PDFs and clear error messages | Done | -| 5 | Manual release checklist, then the first NuGet release (1.0.0-rc.1) and the stable 1.0.0 | In progress | -| 6 | PDF to image conversion (PNG, JPG, TIFF), planned after 1.0 | Planned | +| 5 | First NuGet release (1.0.0-rc.1, published 2026-11-21) | Done | +| 6 | A proper package page (1.0.0-rc.2), the manual release checklist, then the stable 1.0.0 | In progress | +| 7 | PDF to image conversion (PNG, JPG, TIFF), planned after 1.0 | Planned | ## Get involved diff --git a/SECURITY.md b/SECURITY.md index feab84e..43f21e4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -28,8 +28,10 @@ advisory unless you prefer not to be named. | Older releases | No: update to the latest release | | Builds from source | No: use the latest release, or the latest commit on `main` | -Version 1.0.0-rc.1 is the first release of PDFStream.NET (the package `PDFStream.NET`). It has not been published on -NuGet yet; until it is, fixes land on `main` only. +Version 1.0.0-rc.1, the first release of PDFStream.NET (the package `PDFStream.NET`), was published on +[nuget.org](https://www.nuget.org/packages/PDFStream.NET) on 2026-11-21. Version 1.0.0-rc.2 is the version with the +new package page; its library code is the same as 1.0.0-rc.1. Security fixes are released as new versions on +nuget.org, so update to the latest 1.0.0-rc.x (and later the stable 1.0.0) to receive them. ## PDFium, the PDF engine diff --git a/docs/release-checklist.md b/docs/release-checklist.md index fa1c4cf..0ff0285 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -6,6 +6,15 @@ and (for a failure) opened an issue. Never change a result to Pass from memory. How to read the result column: **Pass**, **Fail** (write what happened), **Not run**. +## Releases so far + +| Version | On nuget.org | Manual checks (section 2) at the time | +| --- | --- | --- | +| 1.0.0-rc.1 | Published on 2026-11-21, as a prerelease | All rows Not run | +| 1.0.0-rc.2 | The package page release (icon, package readme, description, tags, release notes); the library code is the same as 1.0.0-rc.1. Write the date here once it is published. | All rows Not run | + +The stable 1.0.0 is released only after the open rows in section 2 have been run and recorded. + ## 1. Automated checks (run by the test suite) The real-print acceptance tests print through *Microsoft Print to PDF* into a temporary file, re-open the @@ -59,6 +68,10 @@ Print a multi-page PDF with the sample or your own program built for each archit | Run from a Task Scheduler task ("Run whether user is logged on or not") | | | Not run | | | Run from an IIS application pool: an ASP.NET Core app printing to a printer visible to the app pool identity | | | Not run | | +Reported, not signed off: on 2026-11-21, one real print through an installed print service on one PC was +reported as working. The Windows service row above stays Not run until someone records the machine, the +service account, the printer, the date and the result in it. + ### 2.3 Printers and paper | Check | Machine | Date | Result | Initials | diff --git a/docs/usage.md b/docs/usage.md index 599ae17..b0b663b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -13,8 +13,9 @@ Windows services, scheduled tasks and IIS, read [services-and-iis.md](services-a print system. - Nothing else on the machine: no Adobe Reader, no PDF viewer, no licence key. The PDF engine (PDFium) comes with the package for 64-bit (x64), 32-bit (x86) and Arm64 Windows, and your build picks the right one. -- The NuGet package is `PDFStream.NET` (`dotnet add package PDFStream.NET`); in code you write - `using PDFStream.NET;`. +- The NuGet package is `PDFStream.NET`. While only prereleases exist, add it with + `dotnet add package PDFStream.NET --prerelease` (a plain `dotnet add package PDFStream.NET` finds no stable + version); in code you write `using PDFStream.NET;`. ## The three calls diff --git a/src/PDFStream.NET/PDFStream.NET.csproj b/src/PDFStream.NET/PDFStream.NET.csproj index 8ef9b00..72c6b35 100644 --- a/src/PDFStream.NET/PDFStream.NET.csproj +++ b/src/PDFStream.NET/PDFStream.NET.csproj @@ -4,7 +4,12 @@ PDFStream.NET PDFStream.NET - Free, open-source silent PDF printing for .NET on Windows, powered by PDFium. No Adobe Reader, no licence keys, no watermarks. + + Silent PDF printing for .NET on Windows: print a PDF file, stream or byte array to any local or network printer in one call, with no print dialog and no Adobe Reader. Made for Windows services, background jobs and servers that print unattended. Free and open source (MIT), powered by the bundled PDFium engine, with no licence keys, watermarks or telemetry. PDFStream.NET PDFStream.NET - pdf;print;printing;printer;silent;pdfium;windows;service + + pdf;print;printing;printer;silent;windows;pdfium;batch;automation;server;service;pdf-printing + + icon.png + README.md + + 1.0.0-rc.2 gives the package a proper nuget.org page: an icon, a readme written for nuget.org, a clearer description, search tags and these release notes. The library code is unchanged from 1.0.0-rc.1. Full changelog: https://github.com/P4Software/PDFStream.NET/blob/main/CHANGELOG.md https://github.com/P4Software/PDFStream.NET https://github.com/P4Software/PDFStream.NET git @@ -30,11 +41,20 @@ - + + + diff --git a/src/PDFStream.NET/README.nuget.md b/src/PDFStream.NET/README.nuget.md new file mode 100644 index 0000000..8be8688 --- /dev/null +++ b/src/PDFStream.NET/README.nuget.md @@ -0,0 +1,136 @@ +# PDFStream.NET + +**Silent PDF printing for .NET on Windows.** Send a PDF to any printer Windows can see in one call: no print +dialog, no Adobe Reader, no licence key. + +[![NuGet](https://img.shields.io/nuget/vpre/PDFStream.NET?label=NuGet&color=0A5FAD)](https://www.nuget.org/packages/PDFStream.NET) [![Licence: MIT](https://img.shields.io/badge/licence-MIT-0A5FAD)](https://github.com/P4Software/PDFStream.NET/blob/main/LICENSE) [![Platform: Windows](https://img.shields.io/badge/platform-Windows-0A5FAD)](https://github.com/P4Software/PDFStream.NET/blob/main/docs/usage.md#requirements) [![.NET 8 and 10](https://img.shields.io/badge/.NET-8%20%7C%2010-0A5FAD)](https://dotnet.microsoft.com/download) + +> **Release candidate.** The library is complete and its automated tests pass. Some manual release checks are +> still open; the **Status** section below says exactly what has and has not been verified. + +## Why PDFStream.NET + +- **Free and open source.** MIT licence: use it in personal, commercial and closed-source software, with no fees. +- **Nothing to activate.** No licence keys, watermarks, expiry dates, telemetry or network calls. +- **Nothing else to install.** No Adobe Reader or other PDF viewer: the PDFium engine comes with the package. +- **Made for unattended printing.** Background jobs, Windows services and servers that print with nobody at the + screen. +- **Plain-language results.** Bad input and printer problems come back as a status and a message that says what + went wrong and what to do next, not as exceptions. + +## Features + +| Feature | Details | +| --- | --- | +| **Input** | A file path, a `Stream` or a `byte[]` | +| **Printers** | Any printer Windows lists, local or network (`\\server\printer`), including virtual printers such as *Microsoft Print to PDF* | +| **Options** | Page ranges (`"1-3, 7"`), copies, duplex, colour or black and white, fit to page or actual size, paper source, print to a file | +| **PDFs** | Password-protected PDFs; filled-in form fields (AcroForm) print with their values | +| **Results** | `PrintResult`: a `PrintStatus` to branch on, a message for people, and the number of pages sent | +| **Threads** | Safe to call from several threads at once | +| **Cancelling** | An optional `CancellationToken`, checked between pages | +| **Engine** | PDFium, the open-source engine of Chrome, for x64, x86 and Arm64 Windows | + +## Quick start + +```csharp +using PDFStream.NET; + +PrintResult result = PdfPrinter.Print("invoice.pdf", new PrintOptions +{ + PrinterName = "Office Printer", // exactly as Windows lists it, or \\server\printer + Copies = 2, +}); + +Console.WriteLine(result.Succeeded + ? $"Sent {result.PagesPrinted} pages to the printer." + : $"Not printed ({result.Status}): {result.Message}"); +``` + +`result.Status` tells your code what happened (`Ok`, `FileNotFound`, `PasswordRequired`, `PrinterNotFound`, +`PrinterUnavailable`, ...) and `result.Message` tells a person what to do about it. + +## Streams, page ranges and duplex + +```csharp +using PDFStream.NET; + +// A PDF from a stream: an upload, a download or a database column. It is read from its current position. +using FileStream pdf = File.OpenRead("monthly-report.pdf"); +using var timeout = new CancellationTokenSource(TimeSpan.FromMinutes(2)); + +PrintResult result = PdfPrinter.Print(pdf, new PrintOptions +{ + PrinterName = @"\\print-server\Finance", + DocumentName = "Monthly report", // the name shown in the print queue + Pages = "1-3, 7", // printed in the order written + Duplex = DuplexMode.LongEdge, // both sides, bound like a book + Color = false, // black and white +}, timeout.Token); +``` + +To print to a file instead of paper, set `PrinterName = "Microsoft Print to PDF"` and +`OutputFile = @"C:\Out\copy.pdf"`: the file is written with no Save As dialog. + +## Install + +```text +dotnet add package PDFStream.NET --prerelease +``` + +or name the version: + +```text +dotnet add package PDFStream.NET --version 1.0.0-rc.2 +``` + +Until the stable 1.0.0 is released, add `--prerelease` or the version, and tick "Include prerelease" in the +Visual Studio package manager. The package, the assembly and the namespace are all `PDFStream.NET`. + +## Requirements + +- Windows 10 or Windows Server 2016, or newer. +- A project that targets `net8.0-windows` or `net10.0-windows` (or newer). Plain `net8.0` cannot reference it, + because printing goes through the Windows print system. +- Nothing else on the machine. The `bblanchon.PDFium.Win32` dependency brings `pdfium.dll` for x64, x86 and + Arm64, and your build puts the right one next to your program. + +## Status + +> **Version 1.0.0-rc.2 is a release candidate (a prerelease).** It changes the package page only: the library +> code is the same as in 1.0.0-rc.1. +> +> **Verified:** the full automated test suite on `net8.0-windows` and `net10.0-windows`, in 64-bit and 32-bit +> processes, including real prints to *Microsoft Print to PDF* whose output is checked page by page; the package +> used from a separate app that printed through it. +> +> **Reported, not verified:** one real print through an installed print service on one PC was reported as +> working. That is a single report, so the checklist row for Windows services stays open. +> +> **Not verified yet:** Arm64 hardware, a scheduled task, IIS, and other physical and duplex printers. These rows +> of the [release checklist](https://github.com/P4Software/PDFStream.NET/blob/main/docs/release-checklist.md) are still open. The stable 1.0.0 follows +> once they are verified. + +## Security and limits + +- **PDFium runs inside your process, without a sandbox.** A malformed or hostile PDF that crashes it ends the + whole process. Print PDFs you do not trust in a separate worker process. +- **One hung printer driver stalls every print in the process**, because one lock guards the PDF engine. + Cancellation is checked between pages, so it cannot interrupt a page that is being drawn. +- **Form printing has two known limits:** a crafted PDF can make it use a lot of memory, and in PDFs whose form + pages share one content array, later pages can show earlier pages' fields. + +Read [Security and limits](https://github.com/P4Software/PDFStream.NET/blob/main/docs/usage.md#security-and-limits) before printing PDFs from outside +your organisation, and report vulnerabilities privately as described in the +[security policy](https://github.com/P4Software/PDFStream.NET/blob/main/SECURITY.md). + +## Documentation + +- [Usage guide](https://github.com/P4Software/PDFStream.NET/blob/main/docs/usage.md): every option, every status and its message. +- [Services, scheduled tasks and IIS](https://github.com/P4Software/PDFStream.NET/blob/main/docs/services-and-iis.md): printing with nobody at the screen. +- [Troubleshooting](https://github.com/P4Software/PDFStream.NET/blob/main/docs/troubleshooting.md), organised by the message you got. +- [Changelog](https://github.com/P4Software/PDFStream.NET/blob/main/CHANGELOG.md) and [release checklist](https://github.com/P4Software/PDFStream.NET/blob/main/docs/release-checklist.md). +- [Issues](https://github.com/P4Software/PDFStream.NET/issues): bugs, printer and driver reports, questions. +- [MIT licence](https://github.com/P4Software/PDFStream.NET/blob/main/LICENSE) and [third-party notices](https://github.com/P4Software/PDFStream.NET/blob/main/THIRD-PARTY-NOTICES.md). + +Made by [P4 Software](https://github.com/P4Software). Source code: [github.com/P4Software/PDFStream.NET](https://github.com/P4Software/PDFStream.NET). diff --git a/src/PDFStream.NET/icon.png b/src/PDFStream.NET/icon.png new file mode 100644 index 0000000..085d413 Binary files /dev/null and b/src/PDFStream.NET/icon.png differ diff --git a/tools/make-icon.ps1 b/tools/make-icon.ps1 new file mode 100644 index 0000000..cc7ca87 --- /dev/null +++ b/tools/make-icon.ps1 @@ -0,0 +1,183 @@ +#Requires -Version 7.0 +<# +.SYNOPSIS + Draws the PDFStream.NET package icon (src/PDFStream.NET/icon.png) from code. + +.DESCRIPTION + The icon is generated, not hand-edited, so that anyone can rebuild exactly the same picture and change it in + review like any other source file. Run it from anywhere: + + pwsh -File tools/make-icon.ps1 + + What it draws, on a 256 x 256 transparent canvas: + - a rounded tile in P4 Blue (#0A5FAD), so the icon keeps its shape on the white nuget.org page and in the + light and dark themes of IDE package managers; + - a white PDF page with a folded corner in P4 Orange (#FBAD48), carrying a downward double chevron (the + "stream" of pages flowing into the printer); + - a white printer body in front of the page, with a Deep Navy (#084A8A) paper slot, an orange status light + and a printed sheet (two blue lines of "text") coming out of the slot. + + Only flat brand colours are used (no gradients, no text, no third-party artwork or fonts), and every shape is + large enough to survive being shown at 32 px, which is how small NuGet clients draw package icons. + + Quality: the picture is drawn at four times the final size with anti-aliasing and then reduced with + high-quality bicubic filtering. That gives smoother edges than anti-aliasing at 256 px alone. + + Needs only PowerShell 7 on Windows: System.Drawing ships with it. No Node, NPM or image tools. +#> +[CmdletBinding()] +param( + # Where the PNG is written. The default is the file the library project packs as the package icon. + [string] $OutputPath = (Join-Path $PSScriptRoot '..' 'src' 'PDFStream.NET' 'icon.png') +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +Add-Type -AssemblyName System.Drawing + +# Final size in pixels, and the supersampling factor used while drawing. +$size = 256 +$scale = 4 + +# Brand colours (P4 Software brand guidelines). Nothing else is used. +$p4Blue = [System.Drawing.ColorTranslator]::FromHtml('#0A5FAD') +$deepNavy = [System.Drawing.ColorTranslator]::FromHtml('#084A8A') +$p4Orange = [System.Drawing.ColorTranslator]::FromHtml('#FBAD48') +$white = [System.Drawing.Color]::White + +<# + Every coordinate below is written in the 256 px design grid and multiplied by the supersampling factor here, + so the geometry stays readable. +#> +function ConvertTo-Canvas([double] $value) { [single]($value * $scale) } + +# A rectangle with rounded corners, as a closed path. Each corner can have its own radius (0 = square). +function New-RoundedRectanglePath { + param( + [double] $X, [double] $Y, [double] $Width, [double] $Height, + [double] $TopLeft, [double] $TopRight, [double] $BottomRight, [double] $BottomLeft + ) + $path = [System.Drawing.Drawing2D.GraphicsPath]::new() + $l = ConvertTo-Canvas $X; $t = ConvertTo-Canvas $Y + $r = ConvertTo-Canvas ($X + $Width); $b = ConvertTo-Canvas ($Y + $Height) + $corner = { param($radius) [single](2 * (ConvertTo-Canvas $radius)) } + + if ($TopLeft -gt 0) { $d = & $corner $TopLeft; $path.AddArc($l, $t, $d, $d, 180, 90) } else { $path.AddLine($l, $t, $l, $t) } + if ($TopRight -gt 0) { $d = & $corner $TopRight; $path.AddArc($r - $d, $t, $d, $d, 270, 90) } else { $path.AddLine($r, $t, $r, $t) } + if ($BottomRight -gt 0) { $d = & $corner $BottomRight; $path.AddArc($r - $d, $b - $d, $d, $d, 0, 90) } else { $path.AddLine($r, $b, $r, $b) } + if ($BottomLeft -gt 0) { $d = & $corner $BottomLeft; $path.AddArc($l, $b - $d, $d, $d, 90, 90) } else { $path.AddLine($l, $b, $l, $b) } + $path.CloseFigure() + return $path +} + +# A closed polygon from design-grid points given as pairs: x1, y1, x2, y2, ... +function New-PolygonPath([double[]] $Coordinates) { + $points = for ($i = 0; $i -lt $Coordinates.Count; $i += 2) { + [System.Drawing.PointF]::new((ConvertTo-Canvas $Coordinates[$i]), (ConvertTo-Canvas $Coordinates[$i + 1])) + } + $path = [System.Drawing.Drawing2D.GraphicsPath]::new() + $path.AddPolygon([System.Drawing.PointF[]] $points) + return $path +} + +function Invoke-Fill($graphics, $color, $path) { + $brush = [System.Drawing.SolidBrush]::new($color) + try { $graphics.FillPath($brush, $path) } finally { $brush.Dispose(); $path.Dispose() } +} + +$big = [System.Drawing.Bitmap]::new($size * $scale, $size * $scale, [System.Drawing.Imaging.PixelFormat]::Format32bppArgb) +$g = [System.Drawing.Graphics]::FromImage($big) +try { + $g.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::AntiAlias + $g.PixelOffsetMode = [System.Drawing.Drawing2D.PixelOffsetMode]::HighQuality + $g.CompositingQuality = [System.Drawing.Drawing2D.CompositingQuality]::HighQuality + $g.Clear([System.Drawing.Color]::Transparent) + + # 1. The tile: the whole canvas, with generous corners like a modern app icon. + Invoke-Fill $g $p4Blue (New-RoundedRectanglePath -X 0 -Y 0 -Width 256 -Height 256 -TopLeft 56 -TopRight 56 -BottomRight 56 -BottomLeft 56) + + # 2. The PDF page. Its top-right corner is cut off along a diagonal, and the folded flap fills the cut. + # The page runs down behind the printer; the printer's outline (step 4) hides its lower part. + $pageLeft = 70; $pageRight = 186; $pageTop = 16; $pageBottom = 160; $fold = 36 + Invoke-Fill $g $white (New-PolygonPath @( + $pageLeft, $pageTop, + ($pageRight - $fold), $pageTop, + $pageRight, ($pageTop + $fold), + $pageRight, $pageBottom, + $pageLeft, $pageBottom)) + # The flap: a right triangle whose right angle points into the page, like paper folded towards the viewer. + Invoke-Fill $g $p4Orange (New-PolygonPath @( + ($pageRight - $fold), $pageTop, + ($pageRight - $fold), ($pageTop + $fold), + $pageRight, ($pageTop + $fold))) + + # 3. The stream: two stacked chevrons pointing down, towards the printer. Round caps and joins keep them + # legible when the icon is reduced to a few pixels. + $pen = [System.Drawing.Pen]::new($p4Blue, (ConvertTo-Canvas 14)) + try { + $pen.StartCap = [System.Drawing.Drawing2D.LineCap]::Round + $pen.EndCap = [System.Drawing.Drawing2D.LineCap]::Round + $pen.LineJoin = [System.Drawing.Drawing2D.LineJoin]::Round + foreach ($top in 64, 90) { + $chevron = [System.Drawing.PointF[]] @( + [System.Drawing.PointF]::new((ConvertTo-Canvas 105), (ConvertTo-Canvas $top)), + [System.Drawing.PointF]::new((ConvertTo-Canvas 128), (ConvertTo-Canvas ($top + 20))), + [System.Drawing.PointF]::new((ConvertTo-Canvas 151), (ConvertTo-Canvas $top))) + $g.DrawLines($pen, $chevron) + } + } finally { $pen.Dispose() } + + # 4. The printer. First an outline in the tile colour, slightly larger than the body, which cuts a clean gap + # between the page and the printer so the page reads as going in behind it; then the body itself. + $bodyLeft = 28; $bodyTop = 132; $bodyWidth = 200; $bodyHeight = 72; $bodyRadius = 20; $gap = 9 + Invoke-Fill $g $p4Blue (New-RoundedRectanglePath -X ($bodyLeft - $gap) -Y ($bodyTop - $gap) -Width ($bodyWidth + 2 * $gap) -Height ($bodyHeight + 2 * $gap) -TopLeft ($bodyRadius + $gap) -TopRight ($bodyRadius + $gap) -BottomRight ($bodyRadius + $gap) -BottomLeft ($bodyRadius + $gap)) + Invoke-Fill $g $white (New-RoundedRectanglePath -X $bodyLeft -Y $bodyTop -Width $bodyWidth -Height $bodyHeight -TopLeft $bodyRadius -TopRight $bodyRadius -BottomRight $bodyRadius -BottomLeft $bodyRadius) + + # 5. The printed sheet coming out of the front. A gap in the tile colour around it separates it from the + # white body; the slot is drawn last, over the top of the sheet, so the sheet seems to come out of it. + $sheetLeft = 80; $sheetRight = 176; $sheetTop = 172; $sheetBottom = 236; $sheetGap = 7 + Invoke-Fill $g $p4Blue (New-RoundedRectanglePath -X ($sheetLeft - $sheetGap) -Y $sheetTop -Width ($sheetRight - $sheetLeft + 2 * $sheetGap) -Height ($sheetBottom - $sheetTop + $sheetGap) -TopLeft 0 -TopRight 0 -BottomRight 0 -BottomLeft 0) + Invoke-Fill $g $white (New-RoundedRectanglePath -X $sheetLeft -Y $sheetTop -Width ($sheetRight - $sheetLeft) -Height ($sheetBottom - $sheetTop) -TopLeft 0 -TopRight 0 -BottomRight 4 -BottomLeft 4) + + # Two lines of "printed" content on the sheet, in the tile blue, so it reads as a page that came out printed. + Invoke-Fill $g $p4Blue (New-RoundedRectanglePath -X 96 -Y 194 -Width 64 -Height 9 -TopLeft 4.5 -TopRight 4.5 -BottomRight 4.5 -BottomLeft 4.5) + Invoke-Fill $g $p4Blue (New-RoundedRectanglePath -X 96 -Y 211 -Width 42 -Height 9 -TopLeft 4.5 -TopRight 4.5 -BottomRight 4.5 -BottomLeft 4.5) + + # The paper slot: one bold Deep Navy bar across the front of the printer. + Invoke-Fill $g $deepNavy (New-RoundedRectanglePath -X 56 -Y 164 -Width 144 -Height 14 -TopLeft 7 -TopRight 7 -BottomRight 7 -BottomLeft 7) + + # The status light, in orange, so the accent colour appears twice and balances the folded corner. + $light = [System.Drawing.Drawing2D.GraphicsPath]::new() + $light.AddEllipse((ConvertTo-Canvas 194), (ConvertTo-Canvas 142), (ConvertTo-Canvas 16), (ConvertTo-Canvas 16)) + Invoke-Fill $g $p4Orange $light +} +finally { $g.Dispose() } + +# Reduce to the final size with high-quality bicubic filtering. TileFlipXY stops the filter from blending the +# transparent area outside the picture into its edges. +$final = [System.Drawing.Bitmap]::new($size, $size, [System.Drawing.Imaging.PixelFormat]::Format32bppArgb) +$fg = [System.Drawing.Graphics]::FromImage($final) +$attributes = [System.Drawing.Imaging.ImageAttributes]::new() +try { + $fg.Clear([System.Drawing.Color]::Transparent) + $fg.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic + $fg.PixelOffsetMode = [System.Drawing.Drawing2D.PixelOffsetMode]::HighQuality + $fg.CompositingQuality = [System.Drawing.Drawing2D.CompositingQuality]::HighQuality + $fg.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::HighQuality + $attributes.SetWrapMode([System.Drawing.Drawing2D.WrapMode]::TileFlipXY) + $fg.DrawImage($big, [System.Drawing.Rectangle]::new(0, 0, $size, $size), 0, 0, $big.Width, $big.Height, [System.Drawing.GraphicsUnit]::Pixel, $attributes) +} +finally { $attributes.Dispose(); $fg.Dispose(); $big.Dispose() } + +try { + $fullPath = [System.IO.Path]::GetFullPath($OutputPath) + [System.IO.Directory]::CreateDirectory([System.IO.Path]::GetDirectoryName($fullPath)) | Out-Null + $final.Save($fullPath, [System.Drawing.Imaging.ImageFormat]::Png) +} +finally { $final.Dispose() } + +$bytes = (Get-Item $fullPath).Length +"Wrote $fullPath ($size x $size, $bytes bytes)." +# nuget.org accepts icons up to 1 MB; this one should stay far below the 100 KB this project allows itself. +if ($bytes -gt 100KB) { throw "The icon is $bytes bytes, more than the 100 KB budget. Simplify the drawing." }