ruby-pwsh 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9ff0bf2c8d109926cd0161323e4d49e6b697410883d5c6da7e8beda5cf8de6d
-  data.tar.gz: da85cd63a46c1d75b0b1178d9841f3d3e134ad20dead8847eb724d52bec3a847
+  metadata.gz: 164dc89d750a5544dd4c100bd2166c0fe9d26447d5636bb18b0eec7d8dfc142f
+  data.tar.gz: bdf317f119bd2e5a7261a711a2a5c4721feda199a955feb5265af07c6f94d8d8
 SHA512:
-  metadata.gz: '09007c0add66995ff0a978129c9b3da760d4d5a9a95bad6bf77226afdcbdeab2508ad68ac39c2217bd5bd57be41904b18333dcba14365441c98582291224782a'
-  data.tar.gz: 2157ae9772fefc54271500a3d7d84502d1737e45fc54986405e45da962fb40fd855d482b4e31aa33febb61756f9d6944f9db82a4fb1f6dcea696ec7f6b81beea
+  metadata.gz: 8430d204e301ce7577148a95d37a8581b3e0d37da1c3e97fcb5dce3c3a2b66601b651dd48ef3a2810d802d09cf28579dfc986712bf407e54ecb3ca8f23ab9283
+  data.tar.gz: ed31dd3ec848dc4c7fd108ee040c5b39e532ea50fe406ba8f98dfb6bb2cf5c804b0d758c393ead8b560785d34717a629380e346f24baae6963e34094889c6fdc

data/.rubocop.yml

@@ -1,3 +1,5 @@
+Gemspec/RequiredRubyVersion:
+  Enabled: false
 Layout/EndOfLine:
   Description: Don't enforce CRLF on Windows.
   Enabled: false
@@ -28,4 +30,12 @@ Naming/FileName:
 Style/RescueStandardError:
   Enabled: false
 Style/ExpandPathArguments:
-  Enabled: false
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  Exclude:
+    - lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb
+Style/ClassVars:
+  Exclude:
+    - lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb

data/.travis.yml

@@ -19,6 +19,7 @@ script:
   - 'bundle exec rake $CHECK'
 rvm:
   - 2.5.1
+  - 2.7
 matrix:
   include:
   - env: CHECK="rubocop"

data/CHANGELOG.md

@@ -2,7 +2,54 @@
 
 All notable changes to this project will be documented in this file.The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
 
-## [0.3.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.3.0) (2019-12-03)
+## [0.6.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.6.0) (2020-11-24)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.5.1...0.6.0)
+
+### Added
+
+- \(GH-81\) Handle parameters in the dsc base provider [\#62](https://github.com/puppetlabs/ruby-pwsh/pull/62) ([michaeltlombardi](https://github.com/michaeltlombardi))
+- \(GH-74\) Remove special handling for ensure in the dsc base provider [\#61](https://github.com/puppetlabs/ruby-pwsh/pull/61) ([michaeltlombardi](https://github.com/michaeltlombardi))
+- \(GH-59\) Refactor away from Simple Provider [\#60](https://github.com/puppetlabs/ruby-pwsh/pull/60) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+### Fixed
+
+- \(GH-57\) Handle datetimes in dsc [\#58](https://github.com/puppetlabs/ruby-pwsh/pull/58) ([michaeltlombardi](https://github.com/michaeltlombardi))
+- \(GH-55\) Handle intentionally empty arrays [\#56](https://github.com/puppetlabs/ruby-pwsh/pull/56) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.5.1](https://github.com/puppetlabs/ruby-pwsh/tree/0.5.1) (2020-09-25)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.5.0...0.5.1)
+
+### Fixed
+
+- \(MAINT\) Ensure dsc provider finds dsc resources during agent run [\#45](https://github.com/puppetlabs/ruby-pwsh/pull/45) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.5.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.5.0) (2020-08-20)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.4.1...0.5.0)
+
+### Added
+
+- \(IAC-1045\) Add the DSC base Puppet provider to pwshlib [\#39](https://github.com/puppetlabs/ruby-pwsh/pull/39) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.4.1](https://github.com/puppetlabs/ruby-pwsh/tree/0.4.1) (2020-02-13)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.4.0...0.4.1)
+
+### Fixed
+
+- Ensure ruby versions older than 2.3 function correctly [\#30](https://github.com/puppetlabs/ruby-pwsh/pull/30) ([binford2k](https://github.com/binford2k))
+
+## [0.4.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.4.0) (2020-01-14)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.3.0...0.4.0)
+
+### Added
+
+- \(MODULES-10389\) Add puppet feature for dependent modules to leverage [\#20](https://github.com/puppetlabs/ruby-pwsh/pull/20) ([sanfrancrisko](https://github.com/sanfrancrisko))
+
+## [0.3.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.3.0) (2019-12-04)
 
 [Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.2.0...0.3.0)
 
@@ -25,4 +72,4 @@ All notable changes to this project will be documented in this file.The format i
 
 
 
-\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/Gemfile

@@ -17,25 +17,20 @@ group :test do
 end
 
 group :development do
-  # TODO: Use gem instead of git. Section mapping is merged into master, but not yet released
-  gem 'github_changelog_generator', git: 'https://github.com/skywinder/github-changelog-generator.git', ref: '20ee04ba1234e9e83eb2ffb5056e23d641c7a018'
+  gem 'github_changelog_generator', '~> 1.15' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.3.0')
   gem 'yard'
 end
 
 group :puppet do
   gem 'pdk', '~> 1.0'
+  gem 'puppet'
 end
 
 group :pry do
   gem 'fuubar'
 
-  if RUBY_VERSION == '1.8.7'
-    gem 'debugger'
-  elsif RUBY_VERSION =~ /^2\.[01]/
-    gem 'byebug', '~> 9.0.0'
+  if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.4.0')
     gem 'pry-byebug'
-  elsif RUBY_VERSION =~ /^2\.[23456789]/
-    gem 'pry-byebug' # rubocop:disable Bundler/DuplicatedGem
   else
     gem 'pry-debugger'
   end

data/README.md

@@ -70,4 +70,50 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). -->
 
+## Releasing the Gem and Puppet Module
+
+Steps to release an update to the gem and module include:
+
+1. Ensure that the release branch is up to date with the master:
+   ```bash
+   git push upstream upstream/master:release --force
+   ```
+1. Checkout a new working branch for the release prep (where xyz is the appropriate version, sans periods):
+   ```bash
+   git checkout -b maint/release/prep-xyz upstream/release
+   ```
+1. Update the version in `lib/pwsh/version.rb` and `metadata.json` to the appropriate version for the new release.
+1. Run the changelog update task (make sure to verify the changelog, correctly tagging PRs as needed):
+   ```bash
+   bundle exec rake changelog
+   ```
+1. Commit your changes with a short, sensible commit message, like:
+   ```text
+   git add lib/pwsh/version.rb
+   git add metadata.json
+   git add CHANGELOG.md
+   git commit -m '(MAINT) Prep for x.y.z release'
+   ```
+1. Push your changes and submit a pull request for review _against the **release** branch_:
+   ```bash
+   git push -u origin maint/release-prep-xyz
+   ```
+1. Ensure tests pass and the code is merged to `release`.
+1. Grab the commit hash from the merge commit on release, use that as the tag for the version (replacing `x.y.z` with the appropriate version and  `commithash` with the relevant one), then push the tags to upstream:
+   ```bash
+   bundle exec rake tag['x.y.z', 'commithash']
+   ```
+1. Build the Ruby gem and publish:
+   ```bash
+   bundle exec rake build
+   bundle exec rake push['ruby-pwsh-x.y.z.gem']
+   ```
+1. Verify that the correct version now exists on [RubyGems](https://rubygems.org/search?query=ruby-pwsh)
+1. Build the Puppet module:
+   ```bash
+   bundle exec rake build_module
+   ```
+1. Publish the updated module version (found in the `pkg` folder) to [the Forge](https://forge.puppet.com/puppetlabs/pwshlib).
+1. Submit the [mergeback PR from the release branch to master](https://github.com/puppetlabs/ruby-pwsh/compare/master...release).
+
 ## Known Issues

data/Rakefile

@@ -61,8 +61,6 @@ end
 desc 'Build the gem'
 task :build do
   gemspec_path = File.join(Dir.pwd, 'ruby-pwsh.gemspec')
-  # Delete the puppet-specific code if it exists
-  FileUtils.rm_r('lib/puppet') if File.exist?('lib/puppet')
   run_local_command("bundle exec gem build '#{gemspec_path}'")
 end
 
@@ -75,7 +73,7 @@ task :tag, [:version, :sha] do |_task, args|
   raise "Invalid version #{args[:version]} - must be like '1.2.3'" unless args[:version] =~ /^\d+\.\d+\.\d+$/
 
   run_local_command('git fetch upstream')
-  run_local_command("git tag -a version -m #{args[:version]} #{args[:sha]}")
+  run_local_command("git tag -a #{args[:version]} -m #{args[:version]} #{args[:sha]}")
   run_local_command('git push upstream --tags')
 end
 

data/appveyor.yml

@@ -0,0 +1,38 @@
+---
+version: 1.1.x.{build}
+branches:
+  only:
+    - main
+    - release
+clone_depth: 10
+environment:
+  matrix:
+    -
+      RUBY_VERSION: 25-x64
+      CHECK: rubocop
+    -
+      RUBY_VERSION: 25
+      CHECK: spec
+      COVERAGE: yes
+matrix:
+  fast_finish: true
+install:
+  - set PATH=C:\Ruby%RUBY_VERSION%\bin;%PATH%
+  - bundle install --jobs 4 --retry 2
+  - type Gemfile.lock
+build: off
+build_script:
+  - dir .
+test_script:
+  - ruby -v
+  - gem -v
+  - bundle -v
+  - pwsh -v
+  - bundle exec rake %CHECK%
+notifications:
+  - provider: Email
+    to:
+      - nobody@nowhere.com
+    on_build_success: false
+    on_build_failure: false
+    on_build_status_changed: false

data/lib/puppet/feature/pwshlib.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'puppet/util/feature'
+
+Puppet.features.add(:pwshlib, libs: ['ruby-pwsh'])

data/lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb

@@ -0,0 +1,739 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'ruby-pwsh'
+require 'pathname'
+require 'json'
+
+class Puppet::Provider::DscBaseProvider
+  # Initializes the provider, preparing the class variables which cache:
+  # - the canonicalized resources across calls
+  # - query results
+  # - logon failures
+  def initialize
+    @@cached_canonicalized_resource = []
+    @@cached_query_results = []
+    @@logon_failures = []
+    super
+  end
+
+  # Look through a cache to retrieve the hashes specified, if they have been cached.
+  # Does so by seeing if each of the specified hashes is a subset of any of the hashes
+  # in the cache, so {foo: 1, bar: 2} would return if {foo: 1} was the search hash.
+  #
+  # @param cache [Array] the class variable containing cached hashes to search through
+  # @param hashes [Array] the list of hashes to search the cache for
+  # @return [Array] an array containing the matching hashes for the search condition, if any
+  def fetch_cached_hashes(cache, hashes)
+    cache.reject do |item|
+      matching_hash = hashes.select { |hash| (item.to_a - hash.to_a).empty? || (hash.to_a - item.to_a).empty? }
+      matching_hash.empty?
+    end.flatten
+  end
+
+  # Implements the canonicalize feature of the Resource API; this method is called first against any resources
+  # defined in the manifest, then again to conform the results from a get call. The method attempts to retrieve
+  # the DSC resource from the machine; if the resource is found, this method then compares the downcased values
+  # of the two hashes, overwriting the manifest value with the discovered one if they are case insensitively
+  # equivalent; this enables case insensitive but preserving behavior where a manifest declaration of a path as
+  # "c:/foo/bar" if discovered on disk as "C:\Foo\Bar" will canonicalize to the latter and prevent any flapping.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param resources [Hash] the hash of the resource to canonicalize from either manifest or invocation
+  # @return [Hash] returns a hash representing the current state of the object, if it exists
+  def canonicalize(context, resources)
+    canonicalized_resources = []
+    resources.collect do |r|
+      if fetch_cached_hashes(@@cached_canonicalized_resource, [r]).empty?
+        canonicalized = invoke_get_method(context, r)
+        if canonicalized.nil?
+          canonicalized = r.dup
+          @@cached_canonicalized_resource << r.dup
+        else
+          canonicalized[:name] = r[:name]
+          if r[:dsc_psdscrunascredential].nil?
+            canonicalized.delete(:dsc_psdscrunascredential)
+          else
+            canonicalized[:dsc_psdscrunascredential] = r[:dsc_psdscrunascredential]
+          end
+          downcased_result = recursively_downcase(canonicalized)
+          downcased_resource = recursively_downcase(r)
+          downcased_result.each do |key, value|
+            canonicalized[key] = r[key] unless downcased_resource[key] == value
+            canonicalized.delete(key) unless downcased_resource.keys.include?(key)
+          end
+          # Cache the actually canonicalized resource separately
+          @@cached_canonicalized_resource << canonicalized.dup
+        end
+      else
+        canonicalized = r
+      end
+      canonicalized_resources << canonicalized
+    end
+    context.debug("Canonicalized Resources: #{canonicalized_resources}")
+    canonicalized_resources
+  end
+
+  # Attempts to retrieve an instance of the DSC resource, invoking the `Get` method and passing any
+  # namevars as the Properties to Invoke-DscResource. The result object, if any, is compared to the
+  # specified properties in the Puppet Resource to decide whether it needs to be created, updated,
+  # deleted, or whether it is in the desired state.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param names [Hash] the hash of namevar properties and their values to use to get the resource
+  # @return [Hash] returns a hash representing the current state of the object, if it exists
+  def get(context, names = nil)
+    # Relies on the get_simple_filter feature to pass the namevars
+    # as an array containing the namevar parameters as a hash.
+    # This hash is functionally the same as a should hash as
+    # passed to the should_to_resource method.
+    context.debug('Collecting data from the DSC Resource')
+
+    # If the resource has already been queried, do not bother querying for it again
+    cached_results = fetch_cached_hashes(@@cached_query_results, names)
+    return cached_results unless cached_results.empty?
+
+    if @@cached_canonicalized_resource.empty?
+      mandatory_properties = {}
+    else
+      canonicalized_resource = @@cached_canonicalized_resource[0].dup
+      mandatory_properties = canonicalized_resource.select do |attribute, _value|
+        (mandatory_get_attributes(context) - namevar_attributes(context)).include?(attribute)
+      end
+      # If dsc_psdscrunascredential was specified, re-add it here.
+      mandatory_properties[:dsc_psdscrunascredential] = canonicalized_resource[:dsc_psdscrunascredential] if canonicalized_resource.keys.include?(:dsc_psdscrunascredential)
+    end
+    names.collect do |name|
+      name = { name: name } if name.is_a? String
+      invoke_get_method(context, name.merge(mandatory_properties))
+    end
+  end
+
+  # Determines whether a resource is ensurable and which message to write (create, update, or delete),
+  # then passes the appropriate values along to the various sub-methods which themselves call the Set
+  # method of Invoke-DscResource. Implementation borrowed directly from the Resource API Simple Provider
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param changes [Hash] the hash of whose key is the name_hash and value is the is and should hashes
+  def set(context, changes)
+    changes.each do |name, change|
+      is = change.key?(:is) ? change[:is] : (get(context, [name]) || []).find { |r| r[:name] == name }
+      context.type.check_schema(is) unless change.key?(:is)
+
+      should = change[:should]
+
+      name_hash = if context.type.namevars.length > 1
+                    # pass a name_hash containing the values of all namevars
+                    name_hash = {}
+                    context.type.namevars.each do |namevar|
+                      name_hash[namevar] = change[:should][namevar]
+                    end
+                    name_hash
+                  else
+                    name
+                  end
+
+      # for compatibility sake, we use dsc_ensure instead of ensure, so context.type.ensurable? does not work
+      if !context.type.attributes.key?(:dsc_ensure)
+        is = create_absent(:name, name) if is.nil?
+        should = create_absent(:name, name) if should.nil?
+
+        # HACK: If the DSC Resource is ensurable but doesn't report a default value
+        # for ensure, we assume it to be `Present` - this is the most common pattern.
+        should_ensure = should[:dsc_ensure].nil? ? 'Present' : should[:dsc_ensure].to_s
+        is_ensure = is[:dsc_ensure].to_s
+
+        if is_ensure == 'Absent' && should_ensure == 'Present'
+          context.creating(name) do
+            create(context, name_hash, should)
+          end
+        elsif is_ensure == 'Present' && should_ensure == 'Present'
+          context.updating(name) do
+            update(context, name_hash, should)
+          end
+        elsif is_ensure == 'Present' && should_ensure == 'Absent'
+          context.deleting(name) do
+            delete(context, name_hash)
+          end
+        end
+      else
+        context.updating(name) do
+          update(context, name_hash, should)
+        end
+      end
+    end
+  end
+
+  # Creates a hash with the name / name_hash and sets dsc_ensure to absent for comparison
+  # purposes; this handles cases where the resource isn't found on the node.
+  #
+  # @param namevar [Object] the name of the variable being used for the resource name
+  # @param title [Hash] the hash of namevar properties and their values
+  # @return [Hash] returns a hash representing the absent state of the resource
+  def create_absent(namevar, title)
+    result = if title.is_a? Hash
+               title.dup
+             else
+               { namevar => title }
+             end
+    result[:dsc_ensure] = 'Absent'
+    result
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `update`, or `delete` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def create(context, name, should)
+    context.debug("Creating '#{name}' with #{should.inspect}")
+    invoke_set_method(context, name, should)
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `create`, or `delete` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def update(context, name, should)
+    context.debug("Updating '#{name}' with #{should.inspect}")
+    invoke_set_method(context, name, should)
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `create`, or `update` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def delete(context, name)
+    context.debug("Deleting '#{name}'")
+    invoke_set_method(context, name, name.merge({ dsc_ensure: 'Absent' }))
+  end
+
+  # Invokes the `Get` method, passing the name_hash as the properties to use with `Invoke-DscResource`
+  # The PowerShell script returns a JSON representation of the DSC Resource's CIM Instance munged as
+  # best it can be for Ruby. Once that JSON is parsed into a hash this method further munges it to
+  # fit the expected property definitions. Finally, it returns the object for the Resource API to
+  # compare against and determine what future actions, if any, are needed.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name_hash [Hash] the hash of namevars to be passed as properties to `Invoke-DscResource`
+  # @return [Hash] returns a hash representing the DSC resource munged to the representation the Puppet Type expects
+  def invoke_get_method(context, name_hash)
+    context.debug("retrieving #{name_hash.inspect}")
+
+    # Do not bother running if the logon credentials won't work
+    return name_hash if !name_hash[:dsc_psdscrunascredential].nil? && logon_failed_already?(name_hash[:dsc_psdscrunascredential])
+
+    query_props = name_hash.select { |k, v| mandatory_get_attributes(context).include?(k) || (k == :dsc_psdscrunascredential && !v.nil?) }
+    resource = should_to_resource(query_props, context, 'get')
+    script_content = ps_script_content(resource)
+    context.debug("Script:\n #{redact_secrets(script_content)}")
+    output = ps_manager.execute(script_content)[:stdout]
+    context.err('Nothing returned') if output.nil?
+
+    data = JSON.parse(output)
+    context.debug("raw data received: #{data.inspect}")
+    error = data['errormessage']
+    unless error.nil?
+      # NB: We should have a way to stop processing this resource *now* without blowing up the whole Puppet run
+      # Raising an error stops processing but blows things up while context.err alerts but continues to process
+      if error =~ /Logon failure: the user has not been granted the requested logon type at this computer/
+        logon_error = "PSDscRunAsCredential account specified (#{name_hash[:dsc_psdscrunascredential]['user']}) does not have appropriate logon rights; are they an administrator?"
+        name_hash[:name].nil? ? context.err(logon_error) : context.err(name_hash[:name], logon_error)
+        @@logon_failures << name_hash[:dsc_psdscrunascredential].dup
+        # This is a hack to handle the query cache to prevent a second lookup
+        @@cached_query_results << name_hash # if fetch_cached_hashes(@@cached_query_results, [data]).empty?
+      else
+        context.err(error)
+      end
+      # Either way, something went wrong and we didn't get back a good result, so return nil
+      return nil
+    end
+    # DSC gives back information we don't care about; filter down to only
+    # those properties exposed in the type definition.
+    valid_attributes = context.type.attributes.keys.collect(&:to_s)
+    parameters = context.type.attributes.select { |_name, properties| [properties[:behaviour]].collect.include?(:parameter) }.keys.collect(&:to_s)
+    data.select! { |key, _value| valid_attributes.include?("dsc_#{key.downcase}") }
+    data.reject! { |key, _value| parameters.include?("dsc_#{key.downcase}") }
+    # Canonicalize the results to match the type definition representation;
+    # failure to do so will prevent the resource_api from comparing the result
+    # to the should hash retrieved from the resource definition in the manifest.
+    data.keys.each do |key| # rubocop:disable Style/HashEachMethods
+      type_key = "dsc_#{key.downcase}".to_sym
+      data[type_key] = data.delete(key)
+      camelcase_hash_keys!(data[type_key]) if data[type_key].is_a?(Enumerable)
+      # Convert DateTime back to appropriate type
+      data[type_key] = Puppet::Pops::Time::Timestamp.parse(data[type_key]) if context.type.attributes[type_key][:mof_type] =~ /DateTime/i
+      # PowerShell does not distinguish between a return of empty array/string
+      #  and null but Puppet does; revert to those values if specified.
+      if data[type_key].nil? && query_props.keys.include?(type_key) && query_props[type_key].is_a?(Array)
+        data[type_key] = query_props[type_key].empty? ? query_props[type_key] : []
+      end
+    end
+    # If a resource is found, it's present, so refill this Puppet-only key
+    data.merge!({ name: name_hash[:name] })
+
+    # Cache the query to prevent a second lookup
+    @@cached_query_results << data.dup if fetch_cached_hashes(@@cached_query_results, [data]).empty?
+    context.debug("Returned to Puppet as #{data}")
+    data
+  end
+
+  # Invokes the `Set` method, passing the should hash as the properties to use with `Invoke-DscResource`
+  # The PowerShell script returns a JSON hash with key-value pairs indicating whether or not the resource
+  # is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param should [Hash] the desired state represented definition to pass as properties to Invoke-DscResource
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def invoke_set_method(context, name, should)
+    context.debug("Invoking Set Method for '#{name}' with #{should.inspect}")
+
+    # Do not bother running if the logon credentials won't work
+    return nil if !should[:dsc_psdscrunascredential].nil? && logon_failed_already?(should[:dsc_psdscrunascredential])
+
+    apply_props = should.select { |k, _v| k.to_s =~ /^dsc_/ }
+    resource = should_to_resource(apply_props, context, 'set')
+    script_content = ps_script_content(resource)
+    context.debug("Script:\n #{redact_secrets(script_content)}")
+
+    output = ps_manager.execute(script_content)[:stdout]
+    context.err('Nothing returned') if output.nil?
+
+    data = JSON.parse(output)
+    context.debug(data)
+
+    context.err(data['errormessage']) unless data['errormessage'].empty?
+    # TODO: Implement this functionality for notifying a DSC reboot?
+    # notify_reboot_pending if data['rebootrequired'] == true
+    data
+  end
+
+  # Converts a Puppet resource hash into a hash with the information needed to call Invoke-DscResource,
+  # including the desired state, the path to the PowerShell module containing the resources, the invoke
+  # method, and metadata about the DSC Resource and Puppet Type.
+  #
+  # @param should [Hash] A hash representing the desired state of the DSC resource as defined in Puppet
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param dsc_invoke_method [String] the method to pass to Invoke-DscResource: get, set, or test
+  # @return [Hash] a hash with the information needed to run `Invoke-DscResource`
+  def should_to_resource(should, context, dsc_invoke_method)
+    resource = {}
+    resource[:parameters] = {}
+    %i[name dscmeta_resource_friendly_name dscmeta_resource_name dscmeta_module_name dscmeta_module_version].each do |k|
+      resource[k] = context.type.definition[k]
+    end
+    should.each do |k, v|
+      # PSDscRunAsCredential is considered a namevar and will always be passed, even if nil
+      # To prevent flapping during runs, remove it from the resource definition unless specified
+      next if k == :dsc_psdscrunascredential && v.nil?
+
+      resource[:parameters][k] = {}
+      resource[:parameters][k][:value] = v
+      %i[mof_type mof_is_embedded].each do |ky|
+        resource[:parameters][k][ky] = context.type.definition[:attributes][k][ky]
+      end
+    end
+    resource[:dsc_invoke_method] = dsc_invoke_method
+
+    # Because Puppet adds all of the modules to the LOAD_PATH we can be sure that the appropriate module lives here during an apply;
+    # PROBLEM: This currently uses the downcased name, we need to capture the module name in the metadata I think.
+    # During a Puppet agent run, the code lives in the cache so we can use the file expansion to discover the correct folder.
+    root_module_path = $LOAD_PATH.select { |path| path.match?(%r{#{resource[:dscmeta_module_name].downcase}/lib}) }.first
+    resource[:vendored_modules_path] = if root_module_path.nil?
+                                         File.expand_path(Pathname.new(__FILE__).dirname + '../../../' + 'puppet_x/dsc_resources') # rubocop:disable Style/StringConcatenation
+                                       else
+                                         File.expand_path("#{root_module_path}/puppet_x/dsc_resources")
+                                       end
+    resource[:attributes] = nil
+    context.debug("should_to_resource: #{resource.inspect}")
+    resource
+  end
+
+  # Return a UUID with the dashes turned into underscores to enable the specifying of guaranteed-unique
+  # variables in the PowerShell script.
+  #
+  # @return [String] a uuid with underscores instead of dashes.
+  def random_variable_name
+    # PowerShell variables can't include dashes
+    SecureRandom.uuid.gsub('-', '_')
+  end
+
+  # Return a Hash containing all of the variables defined for instantiation as well as the Ruby hash for their
+  # properties so they can be matched and replaced as needed.
+  #
+  # @return [Hash] containing all instantiated variables and the properties that they define
+  def instantiated_variables
+    @@instantiated_variables ||= {}
+  end
+
+  # Clear the instantiated variables hash to be ready for the next run
+  def clear_instantiated_variables!
+    @@instantiated_variables = {}
+  end
+
+  # Return true if the specified credential hash has already failed to execute a DSC resource due to
+  # a logon error, as when the account is not an administrator on the machine; otherwise returns false.
+  #
+  # @param [Hash] a credential hash with a user and password keys where the password is a sensitive string
+  # @return [Bool] true if the credential_hash has already failed logon, false otherwise
+  def logon_failed_already?(credential_hash)
+    @@logon_failures.any? do  |failure_hash|
+      failure_hash['user'] == credential_hash['user'] && failure_hash['password'].unwrap == credential_hash['password'].unwrap
+    end
+  end
+
+  # Recursively transforms any enumerable, camelCasing any hash keys it finds
+  #
+  # @param enumerable [Enumerable] a string, array, hash, or other object to attempt to recursively downcase
+  # @return [Enumerable] returns the input object with hash keys recursively camelCased
+  def camelcase_hash_keys!(enumerable)
+    if enumerable.is_a?(Hash)
+      enumerable.keys.each do |key| # rubocop:disable Style/HashEachMethods
+        name = key.dup
+        name[0] = name[0].downcase
+        enumerable[name] = enumerable.delete(key)
+        camelcase_hash_keys!(enumerable[name]) if enumerable[name].is_a?(Enumerable)
+      end
+    else
+      enumerable.each { |item| camelcase_hash_keys!(item) if item.is_a?(Enumerable) }
+    end
+  end
+
+  # Recursively transforms any object, downcasing it to enable case insensitive comparisons
+  #
+  # @param object [Object] a string, array, hash, or other object to attempt to recursively downcase
+  # @return [Object] returns the input object recursively downcased
+  def recursively_downcase(object)
+    case object
+    when String
+      object.downcase
+    when Array
+      object.map { |item| recursively_downcase(item) }
+    when Hash
+      transformed = {}
+      object.transform_keys(&:downcase).each do |key, value|
+        transformed[key] = recursively_downcase(value)
+      end
+      transformed
+    else
+      object
+    end
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as mandatory for get operations
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are mandatory for get operations
+  def mandatory_get_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:mandatory_for_get] }.keys
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as mandatory for set operations
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are mandatory for set operations
+  def mandatory_set_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:mandatory_for_set] }.keys
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as namevars
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are namevars
+  def namevar_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:behaviour] == :namevar }.keys
+  end
+
+  # Look through a fully formatted string, replacing all instances where a value matches the formatted properties
+  # of an instantiated variable with references to the variable instead. This allows us to pass complex and nested
+  # CIM instances to the Invoke-DscResource parameter hash without constructing them *in* the hash.
+  #
+  # @param string [String] the string of text to search through for places an instantiated variable can be referenced
+  # @return [String] the string with references to instantiated variables instead of their properties
+  def interpolate_variables(string)
+    modified_string = string
+    # Always replace later-created variables first as they sometimes were built from earlier ones
+    instantiated_variables.reverse_each do |variable_name, ruby_definition|
+      modified_string = modified_string.gsub(format(ruby_definition), "$#{variable_name}")
+    end
+    modified_string
+  end
+
+  # Parses a resource definition (as from `should_to_resource`) for any properties which are PowerShell
+  # Credentials. As these values need to be serialized into PSCredential objects, return an array of
+  # PowerShell lines, each of which instantiates a variable which holds the value as a PSCredential.
+  # These credential variables can then be simply assigned in the parameter hash where needed.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] An array of lines of PowerShell to instantiate PSCredentialObjects and store them in variables
+  def prepare_credentials(resource)
+    credentials_block = []
+    resource[:parameters].each do |_property_name, property_hash|
+      next unless property_hash[:mof_type] == 'PSCredential'
+      next if property_hash[:value].nil?
+
+      variable_name = random_variable_name
+      credential_hash = {
+        'user' => property_hash[:value]['user'],
+        'password' => escape_quotes(property_hash[:value]['password'].unwrap)
+      }
+      instantiated_variables.merge!(variable_name => credential_hash)
+      credentials_block << format_pscredential(variable_name, credential_hash)
+    end
+    credentials_block.join("\n")
+    credentials_block == [] ? '' : credentials_block
+  end
+
+  # Write a line of PowerShell which creates a PSCredential object and assigns it to a variable
+  #
+  # @param variable_name [String] the name of the Variable to assign the PSCredential object to
+  # @param credential_hash [Hash] the Properties which define the PSCredential Object
+  # @return [String] A line of PowerShell which defines the PSCredential object and stores it to a variable
+  def format_pscredential(variable_name, credential_hash)
+    "$#{variable_name} = New-PSCredential -User #{credential_hash['user']} -Password '#{credential_hash['password']}' # PuppetSensitive"
+  end
+
+  # Parses a resource definition (as from `should_to_resource`) for any properties which are CIM instances
+  # whether at the top level or nested inside of other CIM instances, and, where they are discovered, adds
+  # those objects to the instantiated_variables hash as well as returning a line of PowerShell code which
+  # will create the CIM object and store it in a variable. This then allows the CIM instances to be assigned
+  # by variable reference.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] An array of lines of PowerShell to instantiate CIM Instances and store them in variables
+  def prepare_cim_instances(resource)
+    cim_instances_block = []
+    resource[:parameters].each do |_property_name, property_hash|
+      next unless property_hash[:mof_is_embedded]
+
+      # strip dsc_ from the beginning of the property name declaration
+      # name = property_name.to_s.gsub(/^dsc_/, '').to_sym
+      # Process nested CIM instances first as those neeed to be passed to higher-order
+      # instances and must therefore be declared before they must be referenced
+      cim_instance_hashes = nested_cim_instances(property_hash[:value]).flatten.reject(&:nil?)
+      # Sometimes the instances are an empty array
+      unless cim_instance_hashes.count.zero?
+        cim_instance_hashes.each do |instance|
+          variable_name = random_variable_name
+          instantiated_variables.merge!(variable_name => instance)
+          class_name = instance['cim_instance_type']
+          properties = instance.reject { |k, _v| k == 'cim_instance_type' }
+          cim_instances_block << format_ciminstance(variable_name, class_name, properties)
+        end
+      end
+      # We have to handle arrays of CIM instances slightly differently
+      if property_hash[:mof_type] =~ /\[\]$/
+        class_name = property_hash[:mof_type].gsub('[]', '')
+        property_hash[:value].each do |hash|
+          variable_name = random_variable_name
+          instantiated_variables.merge!(variable_name => hash)
+          cim_instances_block << format_ciminstance(variable_name, class_name, hash)
+        end
+      else
+        variable_name = random_variable_name
+        instantiated_variables.merge!(variable_name => property_hash[:value])
+        class_name = property_hash[:mof_type]
+        cim_instances_block << format_ciminstance(variable_name, class_name, property_hash[:value])
+      end
+    end
+    cim_instances_block == [] ? '' : cim_instances_block.join("\n")
+  end
+
+  # Recursively search for and return CIM instances nested in an enumerable
+  #
+  # @param enumerable [Enumerable] a hash or array which may contain CIM Instances
+  # @return [Hash] every discovered hash which does define a CIM Instance
+  def nested_cim_instances(enumerable)
+    enumerable.collect do |key, value|
+      if key.is_a?(Hash) && key.key?('cim_instance_type')
+        key
+        # TODO: Are there any cim instancees 3 levels deep, or only 2?
+        # if so, we should *also* keep searching and processing...
+      elsif key.is_a?(Enumerable)
+        nested_cim_instances(key)
+      elsif value.is_a?(Enumerable)
+        nested_cim_instances(value)
+      end
+    end
+  end
+
+  # Write a line of PowerShell which creates a CIM Instance and assigns it to a variable
+  #
+  # @param variable_name [String] the name of the Variable to assign the CIM Instance to
+  # @param class_name [String] the CIM Class to instantiate
+  # @param property_hash [Hash] the Properties which define the CIM Instance
+  # @return [String] A line of PowerShell which defines the CIM Instance and stores it to a variable
+  def format_ciminstance(variable_name, class_name, property_hash)
+    definition = "$#{variable_name} = New-CimInstance -ClientOnly -ClassName '#{class_name}' -Property #{format(property_hash)}"
+    # AWFUL HACK to make New-CimInstance happy ; it can't parse an array unless it's an array of Cim Instances
+    # definition = definition.gsub("@(@{'cim_instance_type'","[CimInstance[]]@(@{'cim_instance_type'")
+    # EVEN WORSE HACK - this one we can't even be sure it's a cim instance...
+    # but I don't _think_ anything but nested cim instances show up as hashes inside an array
+    definition = definition.gsub('@(@{', '[CimInstance[]]@(@{')
+    interpolate_variables(definition)
+  end
+
+  # Munge a resource definition (as from `should_to_resource`) into valid PowerShell which represents
+  # the `InvokeParams` hash which will be splatted to `Invoke-DscResource`, interpolating all previously
+  # defined variables into the hash.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] A string representing the PowerShell definition of the InvokeParams hash
+  def invoke_params(resource)
+    params = {
+      Name: resource[:dscmeta_resource_friendly_name],
+      Method: resource[:dsc_invoke_method],
+      Property: {}
+    }
+    if resource.key?(:dscmeta_module_version)
+      params[:ModuleName] = {}
+      params[:ModuleName][:ModuleName] = "#{resource[:vendored_modules_path]}/#{resource[:dscmeta_module_name]}/#{resource[:dscmeta_module_name]}.psd1"
+      params[:ModuleName][:RequiredVersion] = resource[:dscmeta_module_version]
+    else
+      params[:ModuleName] = resource[:dscmeta_module_name]
+    end
+    resource[:parameters].each do |property_name, property_hash|
+      # strip dsc_ from the beginning of the property name declaration
+      name = property_name.to_s.gsub(/^dsc_/, '').to_sym
+      params[:Property][name] = case property_hash[:mof_type]
+                                when 'PSCredential'
+                                  # format can't unwrap Sensitive strings nested in arbitrary hashes/etc, so make
+                                  # the Credential hash interpolable as it will be replaced by a variable reference.
+                                  {
+                                    'user' => property_hash[:value]['user'],
+                                    'password' => escape_quotes(property_hash[:value]['password'].unwrap)
+                                  }
+                                when 'DateTime'
+                                  # These have to be handled specifically because they rely on the *Puppet* DateTime,
+                                  # not a generic ruby data type (and so can't go in the shared util in ruby-pwsh)
+                                  "[DateTime]#{property_hash[:value].format('%FT%T%z')}"
+                                else
+                                  property_hash[:value]
+                                end
+    end
+    params_block = interpolate_variables("$InvokeParams = #{format(params)}")
+    # Move the Apostrophe for DateTime declarations
+    params_block = params_block.gsub("'[DateTime]", "[DateTime]'")
+    # HACK: Handle intentionally empty arrays - need to strongly type them because
+    # CIM instances do not do a consistent job of casting an empty array properly.
+    empty_array_parameters = resource[:parameters].select { |_k, v| v[:value].empty? }
+    empty_array_parameters.each do |name, properties|
+      param_block_name = name.to_s.gsub(/^dsc_/, '')
+      params_block = params_block.gsub("#{param_block_name} = @()", "#{param_block_name} = [#{properties[:mof_type]}]@()")
+    end
+    # HACK: make CIM instances work:
+    resource[:parameters].select { |_key, hash| hash[:mof_is_embedded] && hash[:mof_type] =~ /\[\]/ }.each do |_property_name, property_hash|
+      formatted_property_hash = interpolate_variables(format(property_hash[:value]))
+      params_block = params_block.gsub(formatted_property_hash, "[CimInstance[]]#{formatted_property_hash}")
+    end
+    params_block
+  end
+
+  # Given a resource definition (as from `should_to_resource`), return a PowerShell script which has
+  # all of the appropriate function and variable definitions, which will call Invoke-DscResource, and
+  # will correct munge the results for returning to Puppet as a JSON object.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] A string representing the PowerShell script which will invoke the DSC Resource.
+  def ps_script_content(resource)
+    template_path = File.expand_path('../', __FILE__)
+    # Defines the helper functions
+    functions     = File.new("#{template_path}/invoke_dsc_resource_functions.ps1").read
+    # Defines the response hash and the runtime settings
+    preamble      = File.new("#{template_path}/invoke_dsc_resource_preamble.ps1").read
+    # The postscript defines the invocation error and result handling; expects `$InvokeParams` to be defined
+    postscript    = File.new("#{template_path}/invoke_dsc_resource_postscript.ps1").read
+    # The blocks define the variables to define for the postscript.
+    credential_block = prepare_credentials(resource)
+    cim_instances_block = prepare_cim_instances(resource)
+    parameters_block = invoke_params(resource)
+    # clean them out of the temporary cache now that they're not needed; failure to do so can goof up future executions in this run
+    clear_instantiated_variables!
+
+    [functions, preamble, credential_block, cim_instances_block, parameters_block, postscript].join("\n")
+  end
+
+  # Convert a Puppet/Ruby value into a PowerShell representation. Requires some slight additional
+  # munging over what is provided in the ruby-pwsh library, as it does not handle unwrapping Sensitive
+  # data types or interpolating Credentials.
+  #
+  # @param value [Object] The object to format into valid PowerShell
+  # @return [String] A string representation of the input value as valid PowerShell
+  def format(value)
+    Pwsh::Util.format_powershell_value(value)
+  rescue RuntimeError => e
+    raise unless e.message =~ /Sensitive \[value redacted\]/
+
+    string = Pwsh::Util.format_powershell_value(unwrap(value))
+    string.gsub(/#PuppetSensitive'}/, "'} # PuppetSensitive")
+  end
+
+  # Unwrap sensitive strings for formatting, even inside an enumerable, appending '#PuppetSensitive'
+  # to the end of the string in preparation for gsub cleanup.
+  #
+  # @param value [Object] The object to unwrap sensitive data inside of
+  # @return [Object] The object with any sensitive strings unwrapped and annotated
+  def unwrap(value)
+    case value
+    when Puppet::Pops::Types::PSensitiveType::Sensitive
+      "#{value.unwrap}#PuppetSensitive"
+    when Hash
+      unwrapped = {}
+      value.each do |k, v|
+        unwrapped[k] = unwrap(v)
+      end
+      unwrapped
+    when Array
+      unwrapped = []
+      value.each do |v|
+        unwrapped << unwrap(v)
+      end
+      unwrapped
+    else
+      value
+    end
+  end
+
+  # Escape any nested single quotes in a Sensitive string
+  #
+  # @param text [String] the text to escape
+  # @return [String] the escaped text
+  def escape_quotes(text)
+    text.gsub("'", "''")
+  end
+
+  # While Puppet is aware of Sensitive data types, the PowerShell script is not
+  # and so for debugging purposes must be redacted before being sent to debug
+  # output but must *not* be redacted when sent to the PowerShell code manager.
+  #
+  # @param text [String] the text to redact
+  # @return [String] the redacted text
+  def redact_secrets(text)
+    # Every secret unwrapped in this module will unwrap as "'secret' # PuppetSensitive" and, currently,
+    # no known resources specify a SecureString instead of a PSCredential object. We therefore only
+    # need to redact strings which look like password declarations.
+    modified_text = text.gsub(/(?<=-Password )'.+' # PuppetSensitive/, "'#<Sensitive [value redacted]>'")
+    if modified_text =~ /'.+' # PuppetSensitive/
+      # Something has gone wrong, error loudly?
+    else
+      modified_text
+    end
+  end
+
+  # Instantiate a PowerShell manager via the ruby-pwsh library and use it to invoke PowerShell.
+  # Definiing it here allows re-use of a single instance instead of continually instantiating and
+  # tearing a new instance down for every call.
+  def ps_manager
+    debug_output = Puppet::Util::Log.level == :debug
+    # TODO: Allow you to specify an alternate path, either to pwsh generally or a specific pwsh path.
+    Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args, debug: debug_output)
+  end
+end

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_functions.ps1

@@ -0,0 +1,124 @@
+function new-pscredential {
+    [CmdletBinding()]
+    param (
+        [parameter(Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [string]
+        $user,
+
+        [parameter(Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [string]
+        $password
+    )
+
+    $secpasswd = ConvertTo-SecureString $password -AsPlainText -Force
+    $credentials = New-Object System.Management.Automation.PSCredential ($user, $secpasswd)
+    return $credentials
+}
+
+Function ConvertTo-CanonicalResult {
+  [CmdletBinding()]
+  param(
+      [Parameter(Mandatory, Position = 1)]
+      [psobject]
+      $Result,
+
+      [Parameter(DontShow)]
+      [string]
+      $PropertyPath,
+
+      [Parameter(DontShow)]
+      [int]
+      $RecursionLevel = 0
+  )
+
+  $MaxDepth = 5
+  $CimInstancePropertyFilter = { $_.Definition -match 'CimInstance' -and $_.Name -ne 'PSDscRunAsCredential' }
+
+  # Get the properties which are/aren't Cim instances
+  $ResultObject = @{ }
+  $ResultPropertyList = $Result | Get-Member -MemberType Property | Where-Object { $_.Name -ne 'PSComputerName' }
+  $CimInstanceProperties = $ResultPropertyList | Where-Object -FilterScript $CimInstancePropertyFilter
+
+  foreach ($Property in $ResultPropertyList) {
+      $PropertyName = $Property.Name
+      if ($Property -notin $CimInstanceProperties) {
+          $Value = $Result.$PropertyName
+          if ($PropertyName -eq 'Ensure' -and [string]::IsNullOrEmpty($Result.$PropertyName)) {
+              # Just set 'Present' since it was found /shrug
+              # If the value IS listed as absent, don't update it unless you want flapping
+              $Value = 'Present'
+          }
+          else {
+              if ($Value -is [string] -or $value -is [string[]]) {
+                  $Value = $Value
+              }
+
+              if ($Value.Count -eq 1 -and $Property.Definition -match '\\[\\]') {
+                  $Value = @($Value)
+              }
+          }
+      }
+      elseif ($null -eq $Result.$PropertyName) {
+          if ($Property -match 'InstanceArray') {
+              $Value = @()
+          }
+          else {
+              $Value = $null
+          }
+      }
+      elseif ($Result.$PropertyName.GetType().Name -match 'DateTime') {
+          # Handle DateTimes especially since they're an edge case
+          $Value = Get-Date $Result.$PropertyName -UFormat "%Y-%m-%dT%H:%M:%S%Z"
+      }
+      else {
+          # Looks like a nested CIM instance, recurse if we're not too deep in already.
+          $RecursionLevel++
+
+          if ($PropertyPath -eq [string]::Empty) {
+              $PropertyPath = $PropertyName
+          }
+          else {
+              $PropertyPath = "$PropertyPath.$PropertyName"
+          }
+
+          if ($RecursionLevel -gt $MaxDepth) {
+              # Give up recursing more than this
+              return $Result.ToString()
+          }
+
+          $Value = foreach ($item in $Result.$PropertyName) {
+              ConvertTo-CanonicalResult -Result $item -PropertyPath $PropertyPath -RecursionLevel ($RecursionLevel + 1) -WarningAction Continue
+          }
+
+          # The cim instance type is the last component of the type Name
+          # We need to return this for ruby to compare the result hashes
+          # We do NOT need it for the top-level properties as those are defined in the type
+          If ($RecursionLevel -gt 1 -and ![string]::IsNullOrEmpty($Value) ) {
+              # If there's multiple instances, you need to add the type to each one, but you
+              # need to specify only *one* name, otherwise things end up *very* broken.
+              if ($Value.GetType().Name -match '\[\]') {
+                  $Value | ForEach-Object -Process {
+                      $_.cim_instance_type = $Result.$PropertyName.CimClass.CimClassName[0]
+                  }
+              } else {
+                  $Value.cim_instance_type = $Result.$PropertyName.CimClass.CimClassName
+                  # Ensure that, if it should be an array, it is
+                  if ($Result.$PropertyName.GetType().Name -match '\[\]') {
+                      $Value = @($Value)
+                  }
+              }
+          }
+      }
+
+      if ($Property.Definition -match 'InstanceArray') {
+          if ($Value.Count -lt 2) { $Value = @($Value) }
+      }
+
+      $ResultObject.$PropertyName = $Value
+  }
+
+  # Output the final result
+  $ResultObject
+}

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_postscript.ps1

@@ -0,0 +1,23 @@
+Try {
+  $Result = Invoke-DscResource @InvokeParams
+} catch {
+  $Response.errormessage   = $_.Exception.Message
+  return ($Response | ConvertTo-Json -Compress)
+}
+
+# keep the switch for when Test passes back changed properties
+Switch ($invokeParams.Method) {
+  'Test' {
+    $Response.indesiredstate = $Result.InDesiredState
+    return ($Response | ConvertTo-Json -Compress)
+  }
+  'Set' {
+    $Response.indesiredstate = $true
+    $Response.rebootrequired = $Result.RebootRequired
+    return ($Response | ConvertTo-Json -Compress)
+  }
+  'Get' {
+    $CanonicalizedResult = ConvertTo-CanonicalResult -Result $Result
+    return ($CanonicalizedResult | ConvertTo-Json -Compress -Depth 10)
+  }
+}

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_preamble.ps1

@@ -0,0 +1,8 @@
+$script:ErrorActionPreference = 'Stop'
+$script:WarningPreference = 'SilentlyContinue'
+
+$response = @{
+    indesiredstate = $false
+    rebootrequired = $false
+    errormessage   = ''
+}

data/lib/pwsh.rb

@@ -14,10 +14,10 @@ require 'logger'
 module Pwsh
   # Standard errors
   class Error < StandardError; end
+
   # Create an instance of a PowerShell host and manage execution of PowerShell code inside that host.
   class Manager
-    attr_reader :powershell_command
-    attr_reader :powershell_arguments
+    attr_reader :powershell_command, :powershell_arguments
 
     # We actually want this to be a class variable.
     @@instances = {} # rubocop:disable Style/ClassVars
@@ -54,7 +54,7 @@ module Pwsh
       if manager.nil? || !manager.alive?
         # ignore any errors trying to tear down this unusable instance
         begin
-          manager&.exit
+          manager.exit unless manager.nil? # rubocop:disable Style/SafeNavigation
         rescue
           nil
         end
@@ -70,7 +70,7 @@ module Pwsh
     def self.win32console_enabled?
       @win32console_enabled ||= defined?(Win32) &&
                                 defined?(Win32::Console) &&
-                                Win32::Console.class == Class
+                                Win32::Console.instance_of?(Class)
     end
 
     # TODO: This thing isn't called anywhere and the variable it sets is never referenced...
@@ -117,6 +117,7 @@ module Pwsh
         # This named pipe path is Windows specific.
         pipe_path = "\\\\.\\pipe\\#{named_pipe_name}"
       else
+        require 'tmpdir'
         # .Net implements named pipes under Linux etc. as Unix Sockets in the filesystem
         # Paths that are rooted are not munged within C# Core.
         # https://github.com/dotnet/corefx/blob/94e9d02ad70b2224d012ac4a66eaa1f913ae4f29/src/System.IO.Pipes/src/System/IO/Pipes/PipeStream.Unix.cs#L49-L60
@@ -470,7 +471,7 @@ Invoke-PowerShellUserCode @params
     # @return [String] The UTF-8 encoded string containing the payload
     def self.read_length_prefixed_string!(bytes)
       # 32 bit integer in Little Endian format
-      length = bytes.slice!(0, 4).unpack('V').first
+      length = bytes.slice!(0, 4).unpack1('V')
       return nil if length.zero?
 
       bytes.slice!(0, length).force_encoding(Encoding::UTF_8)
@@ -585,7 +586,7 @@ Invoke-PowerShellUserCode @params
 
       pipe_reader = Thread.new(@pipe) do |pipe|
         # Read a Little Endian 32-bit integer for length of response
-        expected_response_length = pipe.sysread(4).unpack('V').first
+        expected_response_length = pipe.sysread(4).unpack1('V')
 
         next nil if expected_response_length.zero?
 

data/lib/pwsh/util.rb

@@ -12,7 +12,7 @@ module Pwsh
     def on_windows?
       # Ruby only sets File::ALT_SEPARATOR on Windows and the Ruby standard
       # library uses that to test what platform it's on.
-      !!File::ALT_SEPARATOR # rubocop:disable Style/DoubleNegation
+      !!File::ALT_SEPARATOR
     end
 
     # Verify paths specified are valid directories which exist.
@@ -117,16 +117,16 @@ module Pwsh
     #
     # @return [String] representation of the value for interpolation
     def format_powershell_value(object)
-      if %i[true false].include?(object) || %w[trueclass falseclass].include?(object.class.name.downcase) # rubocop:disable Lint/BooleanSymbol
+      if %i[true false].include?(object) || %w[trueclass falseclass].include?(object.class.name.downcase)
         "$#{object}"
-      elsif object.class.name == 'Symbol' || object.class.ancestors.include?(Numeric)
+      elsif object.instance_of?(Symbol) || object.class.ancestors.include?(Numeric)
         object.to_s
-      elsif object.class.name == 'String'
+      elsif object.instance_of?(String)
         "'#{escape_quotes(object)}'"
-      elsif object.class.name == 'Array'
-        '@(' + object.collect { |item| format_powershell_value(item) }.join(', ') + ')'
-      elsif object.class.name == 'Hash'
-        '@{' + object.collect { |k, v| format_powershell_value(k) + ' = ' + format_powershell_value(v) }.join('; ') + '}'
+      elsif object.instance_of?(Array)
+        "@(#{object.collect { |item| format_powershell_value(item) }.join(', ')})"
+      elsif object.instance_of?(Hash)
+        "@{#{object.collect { |k, v| "#{format_powershell_value(k)} = #{format_powershell_value(v)}" }.join('; ')}}"
       else
         raise "unsupported type #{object.class} of value '#{object}'"
       end

data/lib/pwsh/version.rb

@@ -2,5 +2,5 @@
 
 module Pwsh
   # The version of the ruby-pwsh gem
-  VERSION = '0.3.0'
+  VERSION = '0.6.0'
 end

data/metadata.json

@@ -1,11 +1,11 @@
 {
   "name": "puppetlabs-pwshlib",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "author": "puppetlabs",
   "summary": "Provide library code for interoperating with PowerShell.",
   "license": "MIT",
   "source": "https://github.com/puppetlabs/ruby-pwsh",
-  "project_page": "https://github.com/puppetlabs/ruby-pwsh/pwshlib.md",
+  "project_page": "https://github.com/puppetlabs/ruby-pwsh/blob/master/pwshlib.md",
   "issues_url": "https://github.com/puppetlabs/ruby-pwsh/issues",
   "dependencies": [
 
@@ -76,7 +76,7 @@
   "requirements": [
     {
       "name": "puppet",
-      "version_requirement": ">= 4.10.0 < 7.0.0"
+      "version_requirement": ">= 5.5.0 < 7.0.0"
     }
   ],
   "pdk-version": "1.13.0",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pwsh
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Puppet, Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-12-04 00:00:00.000000000 Z
+date: 2020-11-24 00:00:00.000000000 Z
 dependencies: []
 description: PowerShell code manager for ruby.
 email:
@@ -31,7 +31,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- appveyor.yml
 - design-comms.png
+- lib/puppet/feature/pwshlib.rb
+- lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_functions.ps1
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_postscript.ps1
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_preamble.ps1
 - lib/pwsh.rb
 - lib/pwsh/util.rb
 - lib/pwsh/version.rb